# Discourse Doc Categories **URL:** https://meta.discourse.org/t/discourse-doc-categories/322376 **Category:** Plugin **Tags:** official, doc-categories **Created:** [August 26, 2024, 11:00pm UTC](https://meta.discourse.org/t/discourse-doc-categories/322376 "2024-08-26T23:00:13Z") **Posts on this page:** 1 **Showing post:** 1
### Author: ![Discourse](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/discourse/32/148734_2.png) [@Discourse](https://meta.discourse.org/u/Discourse) #### Post date: [August 26, 2024, 11:00pm UTC](https://meta.discourse.org/t/discourse-doc-categories/322376/1 "2024-08-26T23:00:13Z")
| | | | | --- | --- | --- | | :discourse2: | **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](https://github.com/discourse/discourse-doc-categories) | | 📖 | **Install Guide** | [How to install plugins in Discourse](https://meta.discourse.org/t/install-plugins-in-discourse/19157) | > [@](#): > > :discourse2: As this is an #official plugin maintained by the Discourse team, #Support, #Contribute > Bug, #Contribute > UX, and #Contribute > Feature requests can be made in the respective categories here on Meta, and tagged with the appropriate plugin tag. Click on a link below to get one started. 👍 > > [❓  **Support**](https://meta.discourse.org/new-topic?category_id=6&body=%3E%20Before%20asking,%20did%20you%20search%20first%3F%20Press%20%F0%9F%94%8D%20at%20the%20upper%20right%20to%20search.&tags=doc-categories "Ask for support on configuring and using Discourse Doc Categories") [🐛  **Bug**](https://meta.discourse.org/new-topic?category_id=1&tags=doc-categories "A bug report means something is broken, preventing normal/typical use of the plugin") [👀  **UX**](https://meta.discourse.org/new-topic?category_id=9&tags=doc-categories "Discussion about the user interface of Discourse Doc Categories, and how features are presented (including language and UI elements)") [💡  **Feature**](https://meta.discourse.org/new-topic?category_id=2&tags=doc-categories "Discussion about how existing Discourse Doc Categories features can be improved or enhanced, and how proposed new features could work") > ⚠ 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](https://meta.discourse.org/t/discourse-docs/130172). 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. ![Settings for the Doc Categories plugin.](https://global.discourse-cdn.com/meta/original/4X/a/8/e/a8e63800b7ccc7b8dff6865197ee3af4eed4509f.png) 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. ![Setting for the index topic of a documentation category.](https://global.discourse-cdn.com/meta/original/4X/9/0/f/90fbdb4fae0d16bd21b906b15ade51b8855d11b3.png) ## Index topics The index topics for a documentation category serve two purposes: 1. They are a central list of all the topics included in the category 2. 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: ```markdown 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: ![Screenshot 2024-09-09 at 09.56.07](https://global.discourse-cdn.com/meta/original/4X/1/c/9/1c9155814526dbc8c087c7b6970a37734d86d1f6.png) > 👀 See the #Documentation > Site Management index topic for an example of a documentation category index in action: [https://meta.discourse.org/t/site-management-index/308032](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). The max number of items in the index is set by the `Max oneboxes per post` site setting, which defaults to 50. If you need more than 50 index items, increase the number in that setting. > Last edited by @nat 2025-10-02T09:02:20Z > > Last checked by @hugh 2024-08-27T01:23:09Z > > > **Check document** > > > > Perform check on document: --- _[View the full topic](https://meta.discourse.org/t/discourse-doc-categories/322376)._