Расширенные функции

Теги контента

Несмотря на наличие иерархической структуры для организации контента в BookStack, иногда возникает необходимость в дополнительной категории для классификации контента. Теги в BookStack предлагают такую гибкость, позволяя добавлять категорию и значения на всех уровнях иерархии.

Формат тегов

Теги в BookStack имеют название, но также могут иметь дополнительное значение. Это позволяет детализировать и классифицировать контент в зависимости от требований конкретного сценария.

tags-list.png

Например, вы можете использовать тег с названием «Критический» без значения для выделения важной приоритетной страницы. Или, если у вас есть диапазон приоритетов, можно использовать тег с названием «Приоритет» и значением «Критический». Таким образом, можно будет легко находить любые страницы с установленным приоритетом, а также конкретно критические страницы.

Это также удобно, если вы хотите использовать теги для метаданных. Например, вы можете записывать даты проверки контента с помощью тега «Дата проверки» и соответствующего значения.

Добавление и управление тегами

Теги можно добавлять на любом уровне иерархии контента (полки, книги, главы и страницы). Их можно применить при редактировании любого элемента. Для полок, книг и глав теги расположены в выпадающем меню на странице редактирования:

tags-edit.png

Для страниц теги можно найти в боковой панели инструмента при редактировании страницы:

tags-page-edit.png

При редактировании имени или значения тега BookStack покажет список существующих подходящих вариантов, чтобы помочь вам быстро заполнить поле. Предложенные значения будут выбраны только для выбранного имени тега, а не для всех тегов.

Также при редактировании можно менять порядок и удалять теги. Все изменения тегов сохраняются вместе с элементом, к которому они применены.

Отображение и обзор тегов

Примененные теги отображаются в нескольких областях BookStack наряду с контентом, к которому они относятся:

При просмотре элемента с тегами можно щелкнуть по тегу, чтобы начать поиск по нему. Щелчок по имени тега начнет поиск всех элементов, имеющих тег с таким же именем. Щелчок по значению запустит поиск элементов с тем же именем тега и значением.

Чтобы просмотреть все используемые теги, можно перейти на страницу обзора тегов через действие «Просмотреть теги», расположенное на индексах книг или полок, или напрямую перейти по адресу /tags. Там вы увидите список всех используемых имен тегов с количеством использований для каждого типа контента.

tags-overview.png

Можно щелкнуть по имени тега или количеству элементов, чтобы запустить соответствующий фильтрованный поиск. Если используются значения тегов, можно также щелкнуть ссылку справа, чтобы получить список всех значений данного тега с аналогичной разбивкой.

Теги в индексе поиска

При индексации контента для поиска в BookStack учитываются имена и значения тегов, и они получают приоритет перед обычным содержимым. Это значит, что вы можете повышать значимость контента в результатах поиска по определенным ключевым словам с помощью тегов.

Операции поиска по тегам

Контент в BookStack можно запрашивать по имени или значению тега. Это можно делать в различных частях BookStack, где доступно окно поиска. Прямо в интерфейсе можно инициировать поиск по тегам, щелкая по самим тегам или статистике в обзоре тегов. Также можно использовать следующую синтаксическую конструкцию:

Допустимые операторы: =, !=, <, >, <=, >=, like. При использовании оператора like можно использовать символ % для обозначения шаблона.

Таким образом, можно выполнять сложные запросы. Например, если вы используете теги «Дата проверки» с датами в формате 20240627 (YYYYMMDD), вы можете найти весь контент с проверочными датами до 2024 года, используя запрос [Дата проверки<20240101].

Теги для кастомизации

Теги также полезны для различных видов кастомизации, даже если они используются лишь как дополнительная метаданные или точки идентификации. Например, вы можете использовать логическую тему для выполнения определенного действия при создании страницы и изменять поведение или действие в зависимости от наличия конкретного тега у родительской книги.

Кроме того, BookStack конвертирует теги в классы в HTML-шаблонах, используемых при просмотре контента, что позволяет легко настраивать стилизацию и оформление на основе тегов. Подробности о классах тегов можно найти в документации по настройке BookStack.

Шаблоны страниц

В BookStack можно отметить страницу как шаблон, чтобы легко использовать её содержимое при редактировании и создании новых страниц. Это особенно полезно, когда требуется создавать множество страниц с похожей структурой.

Создание шаблона страницы

Шаблон страницы в BookStack — это обычная страница, отмеченная как шаблон. Начните с создания или редактирования страницы, которую хотите использовать в качестве шаблона. В боковой панели редактора вы должны увидеть вкладку «Шаблоны». В этой вкладке найдите флажок «Эта страница является шаблоном». Установите этот флажок и сохраните страницу, чтобы превратить её в шаблон. Если вы не видите этот флажок, вероятно, у вас отсутствует системное разрешение роли «Управление шаблонами страниц».

template_checkbox.png

Примечание: Видимость шаблонов страниц контролируется видимостью самой страницы. Если у пользователя нет прав для просмотра страницы, отмеченной как шаблон, она не будет доступна ему в качестве шаблона.

Использование шаблонов страниц

Шаблоны страниц можно использовать при создании или редактировании страницы. В боковой панели редактора вы должны увидеть вкладку «Шаблоны». Если у вас есть доступные шаблоны, они будут перечислены в этом разделе. Также будет отображаться строка поиска для облегчения поиска шаблонов.

Есть несколько способов добавить шаблон в страницу:

template_dragging.png

Помните, что использование шаблона просто копирует его содержимое на момент использования, это не живая связь с шаблоном страницы, и обновление шаблона не повлияет на страницы, которые использовали его ранее.

Шаблоны страниц по умолчанию

Если вы хотите, чтобы новая страница всегда начиналась с определенного шаблона, это можно настроить на уровне книги, используя опцию «Шаблон страницы по умолчанию» при редактировании книги:

templates-default-book.png

С этой опцией, выбранный шаблон будет использоваться для предварительной заполнения содержимого любой новой страницы, созданной в этой книге. Как и в других случаях использования шаблонов, доступ к шаблону будет контролироваться разрешениями. Если пользователь создает страницу в книге, но не имеет доступа к просмотру шаблона, он не будет использован для предварительной заливки содержимого новой страницы.

Роли и разрешения

В BookStack возможности пользователя определяются ролями, которые ему присвоены, и соответствующими разрешениями. Пользователю может быть назначено несколько ролей, в этом случае разрешения суммируются, и пользователь получает любую способность, если хотя бы одна из ролей предоставляет эту возможность.

Управление ролями

Роли могут быть созданы и отредактированы администратором путем перехода в раздел «Настройки > Роли» в интерфейсе BookStack. В новом экземпляре BookStack предоставляется набор стандартных ролей для распространенных случаев использования. При изменении роли вы сможете изменить системные разрешения, которые предоставляют общие системные возможности. Дополнительно, вы увидите набор «Разрешений активов», которые определяют способности членов этой роли по отношению к содержимому в системе. Эти разрешения могут быть перекрыты разрешениями на уровне контента. Многие из разрешений активов имеют опцию «Собственное». Она предоставляет членам этой роли возможность действовать только тогда, когда они являются владельцами элемента в системе.

Назначение ролей

Роли могут быть назначены пользователю администратором через редактирование профиля пользователя в разделе «Настройки > Пользователи» интерфейса BookStack. Здесь нескольким ролям могут быть назначены одному пользователю, и в этом случае разрешения суммируются, и пользователь получит любую способность, если хотя бы одна из ролей предоставляет эту возможность.

Следует учитывать, что некоторые механизмы в BookStack могут изменять роли пользователя. Сюда входят:

Разрешения на уровне контента

Разрешения могут быть перекрыты на уровне полки, книги, главы или страницы, если это необходимо. Это можно сделать с помощью действия «Разрешения» при просмотре такого контента любым пользователем, обладающим разрешением роли «Управлять всеми/своими разрешениями».

book-permissions.png

В представлении разрешений вы можете использовать выпадающее меню «Переопределить разрешения для роли», чтобы выбрать роль для установки разрешений. После сохранения эти индивидуальные разрешения заменят разрешения по умолчанию, предоставленные ролями для сконфигурированного элемента контента.

Доступна опция «Все остальные», которая позволяет изменять или контролировать разрешения для любых ролей, которые специально не перекрываются. По умолчанию для этого элемента будет выбрано «Наследовать значения по умолчанию», что означает, что будут использоваться нормальные разрешения ролей, если они не перекрыты. Снятие отметки с этого флажка позволит использовать указанные разрешения вместо унаследованных.

Разрешения на уровне контента в BookStack обладают следующим поведением:

Когда активны индивидуальные разрешения на уровне контента, влияющие на просматриваемый элемент, вы увидите индикатор в разделе боковой панели сведений. Если у вас есть разрешение на редактирование активных разрешений на уровне контента, этот индикатор действует как ссылка, которая перенаправит вас в соответствующее представление разрешений, даже если они применяются к родительской главе или книге.

permissions-active-indicator.png

Продвинутая логика разрешений

Учитывая разнообразие опций разрешений в BookStack, сценарии и логика могут стать весьма сложными, поскольку они объединяются и накладываются друг на друга. Чтобы упростить понимание взаимодействия разрешений, ниже приведены основные правила, которым следует BookStack. В приведенном ниже тексте «разрешения контента» относятся к тем, которые установлены непосредственно на полки, книги, главы и страницы.

Существуют три основных уровня разрешений, каждый из которых обладает разным уровнем специфичности.
От наименее специфичных к наиболее специфичным:

Исходя из этих уровней:

Повторное использование содержимого страницы

В BookStack может возникнуть ситуация, когда вам потребуется включить один и тот же блок контента в нескольких местах. Конечно, можно копировать и вставлять этот контент вручную, но если потом придется вносить изменения, вам придется обновить его несколько раз на разных страницах. Используя теги включения, вы можете включать целые страницы или отдельные блоки контента из других страниц.

Что нужно учесть

Вот несколько моментов, которые стоит учитывать при повторном использовании контента страницы с помощью тегов включения:

Теги включения

Чтобы включить содержимое одной страницы в другую, можно использовать следующий синтаксис:

{{@page_id}} или {{@page_id#content_id}}

Примеры использования:

Просто введите этот синтаксис в редакторе страницы, и при просмотре страницы контент будет динамически подгружен. Это означает, что вы можете обновить исходный контент, и все изменения будут видны на всех страницах, где этот контент включен.

Легкий способ получения синтаксиса

Найти идентификатор страницы может быть непросто, поэтому в BookStack предусмотрен быстрый и простой способ получения тегов включения. Просмотрите страницу с нужным контентом. Выделите мышью интересующий вас фрагмент, и появится всплывающее окно. По умолчанию оно содержит прямую ссылку на этот контент. Если щелкнуть значок ссылки слева, оно покажет вам тег включения для этого контента. Просто скопируйте его и вставьте в другую страницу. Удалите # и идентификатор блока, чтобы включить всю страницу целиком, а не только конкретный блок.

Принудительное назначение идентификаторов контента

При включении конкретного блока контента используется идентификатор этого блока (часть после хэша). По умолчанию эти идентификаторы генерируются BookStack при сохранении страницы. Если вы используете визуальный редактор (WYSIWYG), идентификатор останется прежним, если блок не будет удален или переформатирован. В редакторе Markdown идентификатор изменяется при каждом сохранении в зависимости от содержимого, поэтому, хотя он может остаться неизменным, велика вероятность изменения идентификатора, поэтому рекомендуется принудительно устанавливать идентификатор, если вы планируете использовать этот контент для включения.

Примечание: Все значения идентификаторов должны начинаться с префикса bkmrk, чтобы избежать их перезаписи.

Визуальный редактор (WYSIWYG)

В визуальном редакторе вы можете принудительно задать идентификатор, перейдя в режим просмотра исходного кода и добавив его вручную:

forcing-wysiwyg-ids.png

Редактор Markdown

В редакторе Markdown вы можете просто вставить HTML с идентификатором, чтобы убедиться, что он не изменится:

# Старый контент
Авторское право компании BookStack 2020

# Исправленный контент с идентификатором
<p id="bkmrk-include-copyright-text">Авторское право компании BookStack 2020</p>

Локализация целевого тега включения

Иногда вам может понадобиться найти страницу, на которую ссылается тег включения. Для этого можно использовать прямые ссылки на страницы BookStack, которые следуют формату <base_url>/link/<page_id>. Возьмите числовой идентификатор (расположенный после @, но перед #, если он присутствует) из тега включения и используйте его в описанном формате URL, и вы окажетесь на целевой странице.

Например, если у вас есть тег включения изображение.png, вы перейдете по пути /link/5. Полный пример URL, используя демонстрационный экземпляр, будет выглядеть так: https://demo.bookstackapp.com/link/5.

Техническая логика включения

BookStack старается умело обрабатывать включения, корректно обрабатывая различные типы контента и соблюдая стандарты HTML. Вот некоторые решения, которые принимает BookStack при обработке включений:

Постоянные ссылки на страницы

URL страницы в BookStack включает «Слаг» (slug), который генерируется на основе названия страницы, а также «Слаг» родительской книги. При изменении названия книги или страницы BookStack использует систему ревизий для попытки разрешения старых ссылок, но некоторые действия могут привести к тому, что старые ссылки на страницы перестанут вести к обновленному содержимому.

Ниже описано, как найти ссылку на страницу на основе идентификатора, если вам нужна стабильная ссылка.

Поиск постоянной ссылки на страницу

Быстрый и простой способ найти постоянную ссылку на страницу встроен в BookStack. Просто выделите любой блок текста на странице, и вы увидите небольшое всплывающее окно. В этом окне будет отображена постоянная ссылка на страницу. Кнопка копирования рядом с полем ввода позволяет скопировать ссылку одним щелчком мыши.

По умолчанию эта ссылка будет содержать компонент #, чтобы URL прокручивал страницу до конкретного выделенного раздела. Если вы не хотите этого, и вместо этого хотите, чтобы ссылка вела просто на страницу без прокрутки, вы можете удалить # и все, что следует за ним, в скопированной ссылке.