 |
Summary | Discourse Doc Categories provides the ability for particular categories to be set aside for documentation, enabling additional features for them. |
 |
Repository Link | https://github.com/discourse/discourse-doc-categories |
 |
Install Guide | How to install plugins in Discourse |
Note that this plugin is in active development and not yet fully complete.
Features
The Discourse Doc Categories plugin that allows you to host structured documentation on an existing Discourse forum. It works by setting aside specific categories for documentation, and providing features to make finding specific documentation topics easier.
You can see it in action at in the Documentation category.
When marking a category as a location for documentation, the following features are enabled for that category:
- A specified topic to be used as an index for all the documentation topics in the category
- A new sidebar for navigating between different topics in the category, including built-in filtering and search functions
- New reports to help you maintain the integrity of the index topics
In addition, the plugin handles redirects for site that are migrating from the retired Docs plugin. Documentation links from that plugin will redirect to their existing topic URLs, and there is a setting for redirecting your previous documentation homepage to your main documentation category.
Configuration
Configuration settings are available at example.discourse.com/admin/site_settings/category/doc_categories. Here you will find the following settings:
-
doc categories enabled: Select to enable the Doc Categories plugin. -
doc categories docs legacy enabled: Select this if you have migrated from the deprecate Docs plugin. -
doc categories homepage: With the previous setting enabled, the landing page from the deprecated Docs plugin will redirect to this URL.
To specify which categories will be used for documentation, assign them an index topic. To do this, open the category’s settings by clicking the 
icon on the category page. From there, click the ‘Settings’ link and scroll down to the ‘Documentation mode’ section. Use the ‘Index topic’ field to specify the topic that will be used for the index of the category.
Index topics
The index topics for a documentation category serve two purposes:
- They are a central list of all the topics included in the category
- The sidebar included with this plugin is populated by the index topic content
Formatting index topics
Index topics can include any content you like. In order for the sidebar to function correctly, they need to include a bulleted list (or mulitiple bulleted lists) of documentation topics. These can simply be the topic URLs in a list, in which case the sidebar will show the full title for each documentation topic.
Having the full title in the sidebar might not be practical if your titles are longer than a few words, so to set shorter titles for a particular topic, precede the URL with a shortened title followed by a colon (:). All the text before the colon will be shown in the sidebar and it will link to the topic URL.
You can divide your index topic into sections and use multiple lists with headings (of any level) above each one - they will then be displayed in the sidebar in these sections.
Here’s an example of an index topic to get you started:
You can start with an optional brief description of the category.
## First section
* https://discourse.example.com/t/topic-title/12
* https://discourse.example.com/t/another-topic-title/34
* Short title: https://discourse.example.com/t/topic-with-a-long-title/56
* Another title: https://discourse.example.com/t/another-topic-with-a-long-title/78
## Second section
* Topic title: https://discourse.example.com/t/documentation-topic/98
* https://discourse.example.com/t/new-topic/76
That example will output a documentation sidebar that looks like this:
See the Site Management index topic for an example of a documentation category index in action: https://meta.discourse.org/t/site-management-index/308032
Maintaining index topics
While the index topics will not be automatically updated as content in the category is added, removed or edited, the plugin includes new reports that highlight where there are inconsistencies within the index topics.
-
Topics not indexed:
example.discourse.com/admin/reports/doc_categories_missing_topics
This report shows any topics in the documentation categories that have not been added to the index. -
Extraneous items:
example.discourse.com/admin/reports/doc_categories_extraneous_items
This report shows items included in the index that look like they should not be there. The report will indicate the reason that the topic has been included in the report - for example, if it has been deleted or it is in a different category to the index topic in which it is included.
Additional info
Adding the string in:docs to a search term will search all categories that are marked for documentation (i.e. they have an index topic assigned).
Last edited by @hugh 2024-09-13T09:52:46Z
Last checked by @hugh 2024-08-27T01:23:09Z
Check document
Perform check on document:
)
I was exploring moving my docs to 
