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

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

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

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

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

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

• Включенный контент не будет проиндексирован как поисковй контент на страницах, в которые он включен.

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

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

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

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

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

• — включает весь контент страницы с идентификатором 5.

• - включает контент из элемента с идентификатором bkmrk-copyright-year на странице с идентификатором 10.

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

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

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

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

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

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

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

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

Редактор Markdown

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

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

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

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

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

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

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

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

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

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

• Идентификаторы включаемых разделов контента будут де-дублированы после обработки включений, что может привести к изменению существующих идентификаторов контента страницы после загрузки содержимого страницы.