 |
Краткое описание | Категории документации Discourse позволяют выделять определённые категории для документации, активируя для них дополнительные функции. |
 |
Ссылка на репозиторий | https://github.com/discourse/discourse-doc-categories |
 |
Руководство по установке | Как установить плагины в Discourse |
Обратите внимание, что этот плагин находится в активной разработке и ещё не полностью завершён.
Функции
Плагин Discourse Doc Categories позволяет размещать структурированную документацию на существующем форуме Discourse. Он работает, выделяя определённые категории для документации и предоставляя функции, упрощающие поиск конкретных тем документации.
Вы можете увидеть его в действии в категории Documentation.
При маркировке категории как места для документации для неё активируются следующие функции:
- Указанная тема, используемая в качестве индекса для всех тем документации в категории
- Новая боковая панель для навигации между различными темами в категории, включая встроенные функции фильтрации и поиска
- Новые отчёты, помогающие поддерживать целостность тем индекса
Кроме того, плагин обрабатывает перенаправления для сайтов, мигрирующих с устаревшего плагина Docs. Ссылки на документацию из того плагина будут перенаправляться на их существующие URL тем, а также существует настройка для перенаправления вашей предыдущей главной страницы документации на основную категорию документации.
Настройка
Настройки конфигурации доступны по адресу example.discourse.com/admin/site_settings/category/doc_categories. Здесь вы найдёте следующие параметры:
doc categories enabled: Выберите, чтобы включить плагин Doc Categories.doc categories docs legacy enabled: Выберите этот параметр, если вы мигрировали с устаревшего плагина Docs.doc categories homepage: При включении предыдущего параметра главная страница устаревшего плагина Docs будет перенаправляться на этот URL.
Чтобы указать, какие категории будут использоваться для документации, назначьте им тему индекса. Для этого откройте настройки категории, нажав на иконку 
на странице категории. Затем нажмите ссылку «Настройки» и прокрутите вниз до раздела «Режим документации». Используйте поле «Тема индекса», чтобы указать тему, которая будет использоваться в качестве индекса категории.
Темы индекса
Темы индекса для категории документации выполняют две функции:
- Они представляют собой центральный список всех тем, включённых в категорию.
- Боковая панель, включённая в этот плагин, заполняется содержимым темы индекса.
Форматирование тем индекса
Темы индекса могут содержать любой контент. Чтобы боковая панель работала корректно, они должны включать маркированный список (или несколько маркированных списков) тем документации. Это могут быть просто URL тем в списке, в этом случае боковая панель будет отображать полное название для каждой темы документации.
Отображение полного названия в боковой панели может быть неудобным, если названия состоят более чем из нескольких слов. Чтобы задать более короткие названия для конкретной темы, поставьте перед URL сокращённое название, за которым следует двоеточие (:). Весь текст до двоеточия будет отображаться в боковой панели, и он будет вести на URL темы.
Вы можете разделить тему индекса на разделы и использовать несколько списков с заголовками (любого уровня) над каждым из них — тогда они будут отображаться в боковой панели в этих разделах.
Вот пример темы индекса для начала:
Вы можете начать с краткого описания категории (необязательно).
## Первый раздел
* https://discourse.example.com/t/topic-title/12
* https://discourse.example.com/t/another-topic-title/34
* Короткое название: https://discourse.example.com/t/topic-with-a-long-title/56
* Другое название: https://discourse.example.com/t/another-topic-with-a-long-title/78
## Второй раздел
* Название темы: https://discourse.example.com/t/documentation-topic/98
* https://discourse.example.com/t/new-topic/76
Этот пример создаст боковую панель документации, которая выглядит так:
Посмотрите тему индекса Documentation > Site Management, чтобы увидеть пример работы индекса категории документации: https://meta.discourse.org/t/site-management-index/308032
Поддержка тем индекса
Хотя темы индекса не обновляются автоматически при добавлении, удалении или редактировании контента в категории, плагин включает новые отчёты, которые выделяют несоответствия в темах индекса.
-
Темы, не включённые в индекс:
example.discourse.com/admin/reports/doc_categories_missing_topics
Этот отчёт показывает любые темы в категориях документации, которые не были добавлены в индекс. -
Лишние элементы:
example.discourse.com/admin/reports/doc_categories_extraneous_items
Этот отчёт показывает элементы, включённые в индекс, которые, по-видимому, не должны там быть. Отчёт указывает причину включения темы в отчёт — например, если она была удалена или находится в другой категории, чем тема индекса, в которую она включена.
Дополнительная информация
Добавление строки in:docs к поисковому запросу выполнит поиск во всех категориях, помеченных для документации (т. е. у которых назначена тема индекса).
Максимальное количество элементов в индексе определяется настройкой сайта «Максимальное количество onebox на пост», по умолчанию равной 50. Если вам нужно более 50 элементов индекса, увеличьте это значение в соответствующей настройке.
)
Я изучал возможность переноса моей документации в 
