BookStack [Документация для пользователей]

• Начало работы
• Обзор содержимого
• Организация содержимого
• Навигация и поиск контента
• Общие функции
• Поиск контента
• Редактор страниц по умолчанию
• Редактор Markdown
• Вложения [Attachments]
• Рисунки и диаграммы
• Экспорт и импорт контента
• Расширенные функции
• Теги контента
• Шаблоны страниц
• Роли и разрешения
• Повторное использование содержимого страницы
• Постоянные ссылки на страницы

Начало работы

Обзор содержимого

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

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

Когда ваши книги начинают накапливаться, вы можете начать использовать полки (bookshelves) для систематизации книг. Одна полка может содержать несколько книг, а одна книга может находиться на нескольких полках.

Цветовая кодировка по умолчанию

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

Начало работы

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

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

Этот фрагмент описывает базовые принципы организации информации в BookStack: от создания книг до управления ими с использованием полок.

Организация содержимого

По мере роста вашего экземпляра BookStack может потребоваться реорганизация контента. В BookStack есть два варианта перемещения контента: перемещение отдельных страниц и глав или сортировка целых книг.

Перемещение отдельных страниц и глав

Страницы и главы можно переместить непосредственно в новую главу или книгу. Чтобы переместить главу или страницу таким способом, перейдите на страницу или главу и выберите пункт «Переместить» в списке действий:

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

Чтобы узнать, какие разрешения требуются для перемещения контента, см. раздел «Разрешения, необходимые для сортировки» ниже.

Сортировка книг

Интерфейс «Сортировка книг» позволяет легко перемещать несколько страниц и глав с помощью простого интерфейса перетаскивания. Чтобы отсортировать содержимое книги, откройте книгу и найдите параметр «Сортировка» в списке действий.

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

Если вы хотите, чтобы книги автоматически сортировались, обратитесь к разделу «Правила сортировки» ниже.

Разрешения, необходимые для сортировки

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

• Право редактирования элемента, который перемещается.

• Право редактирования исходного предсортировочного родителя.

• Если элемент перемещается в новый родительский блок/главу:

  • Право редактирования нового родителя.

  • Право создания типа контента внутри нового родителя.

  • Право удаления типа контента внутри предсортировочного родителя.

Например, если я хочу переместить страницу «Страница А» из Книги А в Книгу Б, мне понадобятся:

• Права редактирования: Страница А, Книга А и Книга Б

• Права создания страниц в Книге Б

• Права удаления страниц в Книге А

Правила сортировки

Правила сортировки могут использоваться для автоматической сортировки контента. Это предварительно заданные операции сортировки, которые могут быть назначены книгам. Они управляются пользователями уровня администратора через вид «Настройки > Сортировка» и позволяют настроить несколько операций сортировки, которые будут выполнены последовательно:

Правила сортировки могут затем использоваться в следующих местах:

• В качестве параметра «Сортировка по умолчанию» в разделе «Настройки > Сортировка», который будет применять настроенную сортировку ко всем вновь создаваемым книгам впоследствии.

• Назначенный конкретной книге с помощью опции «Автоматическая сортировка» в представлении «Сортировка» книги.

• Пакетная привязка к содержимому посредством команды «Назначить правило сортировки».

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

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

Операции правила сортировки

Вот подробности каждой доступной операции правила сортировки:

• Имя - Алфавитный порядок: Базовый алфавитный порядок без учета регистра, основанный на имени.

• Имя - Числовой порядок: Попытается проанализировать числовое значение (например, 24, 24.125) из начала имени и отсортировать его.

• Дата создания: Сортировка по дате создания контента.

• Дата обновления: Сортировка по дате последнего обновления контента.

• Сначала/в конце главы: Перемещает главы в начало/конец упорядоченного списка.

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

Книги и полки

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

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

Навигация и поиск контента

Существует множество способов ориентироваться и находить контент в вашем экземпляре BookStack помимо следования основной иерархии. Ниже приведён обзор некоторых общих вариантов.

Боковая панель книги

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

Ссылки «Следующий» и «Предыдущий»

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

Хлебные крошки [Breadcrumbs]

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

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

Поиск

Один из основных способов нахождения и перехода к контенту — это использование поиска. В шапке сайта находится глобальное поле поиска, где можно искать по всему содержимому вашего экземпляра:

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

Подробнее о поиске читайте далее.

Списки активности

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

Список недавно обновлённых страниц

На домашней странице вы найдете раздел «Недавно обновленные страницы», содержащий самые свежие созданные или обновлённые страницы. Нажимая «Показать всё», вы увидите полный постраничный список.

Избранное

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

 

Общие функции

Поиск контента

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

Поле поиска в шапке

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

Поиск в книге или главе

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

Выбор перемещения и ссылки

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

Расширенный синтаксис поиска

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

Тип поиска | Синтаксис | Примеры | Описание

• Обычный поиск: <термин_1> <термин_2>
  Например: лондон встреча
  Обычные поисковые запросы по словам включают название и описание или тело вашего контента. При вводе нескольких терминов достаточно совпадения одного термина, но контент, содержащий оба термина, будет выше в результатах.

• Точный поиск: "<термин>"
  Например: "лондонская встреча"
  Точные совпадения требуют наличия всей строки в кавычках в точности в таком формате в вашем контенте. Используйте это, если ищете точную фразу или термины с пробелами.

• Поиск по тегам: [<название>], [<оператор><значение>], [<название><оператор><значение>]
  Например: [местоположение], [=лондон], [местоположение=лондон], [участники>5]
  Поиск по тегам позволяет находить страницы с определенными применёнными тегами. Можно искать по названию тега, значению тега или обоим параметрам. При поиске по значению тега необходимо использовать оператор, определяющий тип соответствия. Можно использовать операторы =, !=, <, >, <=, >= или like. При использовании оператора like можно использовать символы % для обозначения шаблонов поиска.

• Фильтры поиска: {<название_фильтра>}, {<название_фильтра>:<значение_фильтра>}
  См. ниже таблицу фильтров, поддерживаемых в BookStack, и способы их использования.

Отрицание поисковых запросов

Для точного поиска, поиска по тегам и фильтрам можно отрицать (НЕ) условие поиска, добавив перед ним дефис (-). Например, поиск с параметром -[местоположение] исключит из результатов поиска все записи с тегом местоположение.

Доступные фильтры

Фильтры представляют собой расширенные возможности поиска, которые можно использовать в поисковом запросе. Ниже представлены все доступные фильтры в BookStack и их использование:

Синтаксис | Примеры | Описание

• Фильтры даты:

  • {updated_after:<дата>}
    Например: {updated_after:2016-12-30}
    Добавляет условие, что контент должен был быть последним обновлен после указанной даты. Дату следует указывать в формате YYYY-MM-DD.

  • {updated_before:<дата>}
    Например: {updated_before:2016-12-30}
    Добавляет условие, что контент должен был быть последним обновлён до указанной даты. Формат такой же: YYYY-MM-DD.

  • {created_after:<дата>}
    Например: {created_after:2016-12-30}
    Условие, что контент должен был быть создан после указанной даты. Формат: YYYY-MM-DD.

  • {created_before:<дата>}
    Например: {created_before:2016-12-30}
    Условие, что контент должен был быть создан до указанной даты. Формат: YYYY-MM-DD.

• Фильтры пользователей:

  • {updated_by:<псевдоним_пользователя|me>}
    Например: {updated_by:барри}, {updated_by:me}
    Условие, что контент должен был быть последний раз обновлен указанным пользователем. Если указать me, будут найдены записи, обновленные текущим пользователем.

  • {created_by:<псевдоним_пользователя|me>}
    Например: {created_by:барри}, {created_by:me}
    Условие, что контент должен был быть создан указанным пользователем. Аналогично me — для текущего пользователя.

  • {owned_by:<псевдоним_пользователя|me>}
    Например: {owned_by:барри}, {owned_by:me}
    Условие, что контент должен активно принадлежать указанному пользователю. Опять же, me означает текущего пользователя.

• Фильтры контента:

  • {in_name:<поиск>}
    Например: {in_name:Лондонские встречи}, {in_name:Встречи}
    Требует, чтобы искомый термин находился в названии контента, а не в теле или описании.

  • {in_body:<поиск>}
    Например: {in_body:Лондонские встречи}, {in_body:Встречи}
    Требует, чтобы искомый термин присутствовал в тексте контента, а не в названии.

• Опционные фильтры:

  • {is_restricted}
    Например: {is_restricted}
    Ограничивает результаты контентом, имеющим активные ограничения на уровне содержимого. Не возвращает элементы с наследуемыми разрешениями.

  • {is_template}
    Например: {is_template}
    Фильтрует результаты поиска страниц, помечая их как шаблон. Обычно комбинируется с фильтром {type:page}.

  • {viewed_by_me}
    Например: {viewed_by_me}
    Возвращает контент, просмотренный текущим пользователем хотя бы один раз.

  • {not_viewed_by_me}
    Например: {not_viewed_by_me}
    Исключает из результатов контент, ранее просмотренный текущим пользователем.

  • {type:<типы_контента>}
    Например: {type:страница|глава|книга}, {type:страница|глава}, {type:книга}
    Ограничивает типы контента, которые будут включены в результаты поиска. Использование зависит от типа поиска. Например, при поиске в главе результат ограничен страницами, и этот фильтр не влияет.

  • {sort_by:<метод_сортировки>}
    Например: {sort_by:last_commented}
    Сортирует результаты поиска определенным порядком, отличным от порядка по соответствию запросу. Поддерживается сортировка по последнему комментарию.

Примеры поиска

Ниже приведены примеры использования вышеуказанного синтаксиса и фильтров:

1. "мой кот" {просмотрено_мной} {обновлено_после:2017-01-24}

   • "мой кот" — поиск контента, содержащего точную фразу «мой кот»;

   • {просмотрено_мной} — просмотрено текущим пользователем;

   • {обновлено_после:2017-01-24} — последнее обновление должно быть после 24 января 2017 года.

2. учебник обсуждение -"черновик" [встреча] {тип:страница} {создано_мной}

   • учебник обсуждение — поиск контента с любыми словами «учебник» или «обсуждение»;

   • -"черновик" — исключение результатов, содержащих точное слово «черновик»;

   • [встреча] — показывать только контент с тегом «встреча»;

   • {тип:страница} — показывать только страницы, скрывая главы и книги;

   • {создано_мной} — созданный текущим пользователем.

3. {тип:книга|глава} {создано_мной} {создано_после:2016-08-12} {создано_до:2017-02-18}

   • {тип:книга|глава} — поиск среди всех книг и глав;

   • {создано_мной} — создано текущим пользователем;

   • {создано_после:2016-08-12} — создание произошло после 12 августа 2016 года;

   • {создано_до:2017-02-18} — но до 18 февраля 2017 года.

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

Редактор страниц по умолчанию

В BookStack по умолчанию используется редактор формата «Что видишь, то и получаешь» (WYSIWYG). Работа с этим редактором похожа на использование привычных текстовых процессоров, таких как Microsoft Word или Google Docs. Тем не менее, для тех, кто предпочитает, доступен альтернативный редактор Markdown, который можно установить в качестве редактора по умолчанию или переключиться на него там, где это разрешено.

Горячие клавиши редактора

В редакторе WYSIWYG доступны следующие сочетания клавиш:

Эти горячие клавиши упрощают процесс редактирования текста, делая его быстрее и эффективнее.

Редактор Markdown

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

Переключение на редактор Markdown

Администратор может настроить выбор редактора по умолчанию при создании новых страниц в разделе настроек «Настройка» («Settings > Customization»).

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

При переходе с WYSIWYG на Markdown вам предложат два варианта:

• Чистый контент — это очищенный вывод Markdown, который выглядит аккуратнее, но может привести к потере оформления или функциональности (например, зависимых от HTML атрибутов или идентификаторов).
• Стабильный контент — сохраняет существующий HTML-код в Markdown, чтобы избежать любых потенциальных проблем с функциональностью или потерей оформления.

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

Горячие клавиши редактора Markdown

В редакторе Markdown доступны следующие комбинации клавиш:

Сочетание клавиш (Windows и Linux/Mac)	Описание
Ctrl + S / Cmd + S	Сохранение черновика
Ctrl + Enter / Cmd + Enter	Сохранение страницы и продолжение работы
Ctrl + 1 / Cmd + 1	Заголовок крупного размера (h2)
Ctrl + 2 / Cmd + 2	Заголовок среднего размера (h3)
Ctrl + 3 / Cmd + 3	Заголовок мелкого размера (h4)
Ctrl + 4 / Cmd + 4	Очень мелкий заголовок (h5)
Ctrl + 5 / Cmd + 5	Обычный абзац
Ctrl + D / Cmd + D
Ctrl + 6 / Cmd + 6	Цитата
Ctrl + Q / Cmd + Q
Ctrl + 7 / Cmd + 7	Блок кода
Ctrl + E / Cmd + E
Ctrl + 8 / Cmd + 8	Встроенный код
Ctrl + Shift + E / Cmd + Shift + E
Ctrl + 9 / Cmd + 9	Выделение (несколько стилей)
Ctrl + O / Cmd + O
Ctrl + P / Cmd + P	Нумерованный список
Ctrl + K / Cmd + K	Вставка ссылки
Ctrl + Shift + K / Cmd + Shift + K	Ссылка на контент BookStack
Ctrl + Shift + I / Cmd + Shift + I	Вставить изображение через URL

Эти сочетания клавиш помогают ускорить процесс редактирования текста в редакторе Markdown.

Вложения [Attachments]

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

Основные цели вложений — это хранение файлов и удобство доступа к ним. BookStack не делает ничего особенного с вложениями, например, сканирует и индексирует их содержимое, так как документация в BookStack предназначена для размещения непосредственно в тексте страниц.

Создание и загрузка вложений

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

Здесь доступны варианты «Загрузить файл» или «Прикрепить ссылку». Вы также можете просто перетащить файл в зону вокруг кнопок, чтобы быстро загрузить файл с устройства. Загрузка файлов — самый распространенный случай, но вы также можете прикрепить ссылку к странице, чтобы использовать её как динамичную, контролируемую ссылку/URL, которую можно использовать и делиться ею.

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

Обратите внимание, что вложения тесно связаны с теми страницами, к которым они были загружены. Доступ к вложению определяется возможностью видеть основную страницу. Если страница удаляется, то вместе с ней удаляются и все прикрепленные к ней вложения!

Доступ к вложениям

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

Альтернативно, вы можете удерживать Ctrl (Cmd на Mac) и щелкнуть на вложении, чтобы оно открылось в новой вкладке. Обратите внимание, что вложения в новых вкладках могут все равно загрузиться, если формат файла считается небезопасным для отображения в новой вкладке или если это поведение браузера по умолчанию.

Использование вложений в страницах

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

Первый способ — просто использовать кнопку «ссылка» на вложении в боковой панели. Щелчок на неё вставит ссылку на вложение в текущее положение курсора в редакторе с правильным URL и именем вложения.

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

Третий способ — обычное использование функционала браузера и редактора. Вы можете скопировать URL вложения, щелкнув правой кнопкой мыши, и затем вставить ссылку обычным способом в страницу, используя скопированный URL вложения.

Технические детали

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

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

Когда вложения открываются встроенно (в новой вкладке или с параметром open=true), BookStack попытается распознать MIME-тип вложения и передать файл с этим типом, чтобы обеспечить просмотр в браузере, если это поддерживается, и если обнаруженный MIME-тип считается безопасным (например, HTML не будет передан встроенно). Это делается с помощью внутреннего белого списка значений MIME-типов.

Рисунки и диаграммы

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

Вставка, редактирование и управление рисунками

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

При работе с визуальным редактором рисунки можно создавать и вставлять на страницу с помощью кнопки на панели инструментов редактора. Эта кнопка расположена в выпадающем меню рядом с таблицами и ссылками:

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

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

Редактор Markdown

В редакторе Markdown рисунок можно вставить с помощью действия, расположенного над областью ввода Markdown-кода:

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

Хранение и формат файлов рисунков

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

Для переносимости и совместимости рисунки сохраняются в формате PNG-файлов, причем оригинальные данные diagrams.net встраиваются внутрь изображения. Поскольку данные рисунка встроены в PNG-изображение, такие рисунки можно продолжать редактировать в любом экземпляре diagrams.net, просто перетащив или импортировав файл изображения.

Экспорт и импорт контента

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

Экспорт

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

• Контейнерный веб-файл
  Файл .html, в который, где возможно, встроены изображения. Такой файл можно открыть в веб-браузере.
  Этот формат обычно обеспечивает наилучшее представление контента BookStack.

• PDF-файл
  Документ в формате .pdf, представляющий ваш контент.
  Выходной файл иногда может быть неточным или лишённым некоторых функций по сравнению с оригинальным представлением в BookStack.

• Простой текстовый файл
  Файл .txt, содержащий только текст вашего контента.

• Файл Markdown
  Файл .md, представляющий ваш контент в формате Markdown.
  Если страница была написана с использованием редактора Markdown, то будет представлен исходный контент. В противном случае система попытается преобразовать контент в Markdown. Получившийся Markdown может всё ещё содержать HTML для некоторых типов контента.

• Портативный ZIP
  Сжатый файл .zip, содержащий данные, файлы вложений и изображения.
  Этот архив можно повторно импортировать в другие экземпляры BookStack, как упомянуто ниже.
  Подробное описание формата можно найти в исходниках BookStack.

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

Для разработчиков многие из этих вариантов экспорта также доступны через REST API BookStack, который предоставляет дополнительные конечные точки, полезные для задач, связанных с экспортом.

Импорт

Если у вас есть соответствующее разрешение роли «Импорт контента», вы можете импортировать архивы в формате «Portable ZIP» (упоминаемые в разделе экспорта) через действие «Импорт», доступное при просмотре верхнего уровня вида «Книги» или по пути /import вашего экземпляра:

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

Для разработчиков подробности формата ZIP-файла для импорта можно найти здесь, либо рассмотреть использование REST API BookStack для импорта.

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

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

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

Формат тегов

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

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

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

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

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

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

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

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

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

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

• В боковой панели или информационной панели при просмотре любого отмеченного элемента.

• В результатах поиска.

• В ответах API для элементов.

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

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

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

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

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

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

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

• Поиск по имени тега:

  • Синтаксис: [<имя>]

  • Пример: [Местоположение]

• Поиск по значению тега:

  • Синтаксис: [<оператор><значение>]

  • Пример: [=Лондон]

• Поиск по имени и значению тега:

  • Синтаксис: [<имя><оператор><значение>]

  • Пример: [Местоположение=Лондон]

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

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

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

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

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

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

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

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

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

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

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

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

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

• Выберите сам блок шаблона, чтобы заменить содержимое редактора содержимым шаблона.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Опция «Роль пользователя по умолчанию после регистрации» в настройках регистрации.

• Синхронизация групп LDAP.

• Синхронизация групп SAML2.

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

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

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

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

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

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

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

• Стандартная роль администратора всегда сохраняет все разрешения для полного контроля, и эта роль не будет конфигурируема в представлениях разрешений.

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

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

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

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

• Разрешения ролей (редактируются через интерфейс «Роли»).

• Разрешения «Все остальные» на уровне контента (редактируются через представление «Разрешения» для элемента).

• Специфичные для роли разрешения на уровне контента (также редактируются через представление «Разрешения» для элемента).

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

• Наиболее специфичное применение разрешений (как указано выше) имеет приоритет и может отменить менее специфичные разрешения.

• Родительские специфичные для роли разрешения контента, которые могут наследоваться (активирована опция «Все остальные»), считаются фактически применимыми к элементу, на который они наследуются, если на более низком уровне нет собственного правила разрешений для этой конкретной роли.

• Где существуют как предоставление, так и отказ в одинаковой степени специфичности, мы склоняемся к предоставлению.

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

В 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 и могут вызывать проблемы, когда браузеры пытаются автоматически исправить ошибки. Это будет выполнено с точностью до положения, насколько это разумно, хотя в некоторых случаях контент может быть перенесен перед или после секции, в которую он включен.

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

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

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

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

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

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

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