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

• Поиск контента
• Редактор страниц по умолчанию
• Редактор Markdown
• Вложения [Attachments]
• Рисунки и диаграммы
• Экспорт и импорт контента

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

Возможность поиска документации критически важна для повседневной работы. Существует несколько мест в 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 для импорта.