 |
Краткое описание | Discourse Doc Categories позволяет выделить определенные категории для документации, предоставляя им дополнительные возможности. |
 |
Ссылка на репозиторий | 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 к поисковому запросу позволит искать во всех категориях, помеченных для документации (т. е. тех, которым назначена тема-оглавление).
Максимальное количество элементов в оглавлении устанавливается настройкой сайта Max oneboxes per post, которая по умолчанию равна 50. Если вам нужно больше 50 элементов в оглавлении, увеличьте это значение в настройке.
)
Я изучал возможность переноса моей документации в 
