# 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:** 20
**Page:** 1
### Author:  [@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.
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:
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:
> 👀 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:
---
### Author:  [@MarcP](https://meta.discourse.org/u/MarcP)
#### Post date: [August 26, 2024, 11:55pm UTC](https://meta.discourse.org/t/discourse-doc-categories/322376/4 "2024-08-26T23:55:05Z")
This is quite nice.. Was just looking into other self-hosted docs solutions (the forum structure can be a bit confusing sometimes for new readers).
Good luck to Discourse (vs. Gitbook & others 😃)
---
### Author:  [@Jagster](https://meta.discourse.org/u/Jagster)
#### Post date: [August 27, 2024, 6:26am UTC](https://meta.discourse.org/t/discourse-doc-categories/322376/5 "2024-08-27T06:26:49Z")
I would guess component `discourse-doc-sidebar` (did I remember the name right) isn’t needed anymore?
---
### Author:  [@hugh](https://meta.discourse.org/u/hugh)
#### Post date: [August 27, 2024, 6:49am UTC](https://meta.discourse.org/t/discourse-doc-categories/322376/6 "2024-08-27T06:49:20Z")
Yes - the component that was originally built for the new documentation sidebar has been moved to this plugin.
---
### Author:  [@AquaL1te](https://meta.discourse.org/u/AquaL1te)
#### Post date: [August 27, 2024, 8:17am UTC](https://meta.discourse.org/t/discourse-doc-categories/322376/7 "2024-08-27T08:17:43Z")
I guess this doesn’t work with tags anymore? 🙂
---
### Author:  [@jrgong](https://meta.discourse.org/u/jrgong)
#### Post date: [August 27, 2024, 9:46am UTC](https://meta.discourse.org/t/discourse-doc-categories/322376/8 "2024-08-27T09:46:28Z")
I love the approach as is neatly integrating into the core discourse navigation instead of a brand new one as in the Docs plugin.
We will be happy to make the switch!
---
### Author:  [@MarcP](https://meta.discourse.org/u/MarcP)
#### Post date: [August 27, 2024, 10:26am UTC](https://meta.discourse.org/t/discourse-doc-categories/322376/9 "2024-08-27T10:26:42Z")
Just dropping this here, _totally not a native feature request_. Even though these might not be specifically applied for this plugin, I do think they are excellent features to have in any docs environment - _as benefit, they could be great core additions too._ 🤔
- Different types of [callouts](https://help.obsidian.md/Editing+and+formatting/Callouts)
- [Hover previews](https://help.obsidian.md/Plugins/Page+preview)
---
### Author:  [@jrgong](https://meta.discourse.org/u/jrgong)
#### Post date: [August 27, 2024, 10:28am UTC](https://meta.discourse.org/t/discourse-doc-categories/322376/10 "2024-08-27T10:28:43Z")
Something like the footnote feature, but globally keyword triggered would be epic for such a feature.
---
### Author:  [@MarcP](https://meta.discourse.org/u/MarcP)
#### Post date: [August 27, 2024, 10:35am UTC](https://meta.discourse.org/t/discourse-doc-categories/322376/11 "2024-08-27T10:35:51Z")
If we have hover previews, which are shown on any internal link on your forum, you don’t even need this, Word/Link replacement can take care of this, and one simply has to hover on a this word and read the full post without opening it 😃
Features like this are very convenient (since no one likes to read docs, right?) and with the release of this plugin, in the middle of my journey of picking the best solution to host my docs, makes it a lot harder difficult for me 😛 I was exploring moving my docs to [Quartz](https://quartz.jzhao.xyz/) with content managed in Obsidian.
---
### Author:  [@jrgong](https://meta.discourse.org/u/jrgong)
#### Post date: [August 27, 2024, 4:51pm UTC](https://meta.discourse.org/t/discourse-doc-categories/322376/12 "2024-08-27T16:51:35Z")
Any chance, it will be compatible with 3.3 stable?
---
### Author:  [@hugh](https://meta.discourse.org/u/hugh)
#### Post date: [August 27, 2024, 10:47pm UTC](https://meta.discourse.org/t/discourse-doc-categories/322376/15 "2024-08-27T22:47:25Z")
Yes, this is fully compatible with Discourse 3.3 🙂
---
### Author:  [@RGJ](https://meta.discourse.org/u/RGJ)
#### Post date: [August 28, 2024, 7:28am UTC](https://meta.discourse.org/t/discourse-doc-categories/322376/16 "2024-08-28T07:28:24Z")
No, it’s not:
```plaintext
/var/www/discourse/plugins/discourse-doc-categories/lib/doc_categories/initializers/invalidate_cache_on_enabled_setting_change.rb:8:in `apply': undefined method `on_enabled_change' for an instance of Plugin::Instance (NoMethodError)
**INCOMPATIBLE PLUGIN**
You are unable to start Discourse due to errors in the plugin at
/var/www/discourse/plugins/discourse-doc-categories
```
See [DEV: Add plugin API to perform actions when the plugin is turned on/o… · discourse/discourse@366dfec · GitHub](https://github.com/discourse/discourse/commit/366dfec16c390a5401e2c056ede25f06ec72c24f)
---
### Author:  [@MarcP](https://meta.discourse.org/u/MarcP)
#### Post date: [August 28, 2024, 8:07am UTC](https://meta.discourse.org/t/discourse-doc-categories/322376/17 "2024-08-28T08:07:47Z")
Emoji rendering in the titles & items in the sidebar would be awesome!
---
### Author:  [@saquetim](https://meta.discourse.org/u/saquetim)
#### Post date: [August 30, 2024, 4:31pm UTC](https://meta.discourse.org/t/discourse-doc-categories/322376/19 "2024-08-30T16:31:50Z")
> [@hugh](#):
>
> Yes, this is fully compatible with Discourse 3.3 🙂
> [@RGJ](#):
>
> No, it’s not:
Hi, guys!
Sorry, this was my error.
I’ve made a mistake when Hugh asked me if the plugin was compatible and assumed the new APIs I introduced in core when I was developing it, did make the cut for 3.3 stable.
Unfortunately, this was not really the case and the first stable version the plugin will be compatible is 3.4.
Again, sorry for the confusion.
---
### Author:  [@thaidb](https://meta.discourse.org/u/thaidb)
#### Post date: [September 1, 2024, 12:32pm UTC](https://meta.discourse.org/t/discourse-doc-categories/322376/20 "2024-09-01T12:32:49Z")
How about group tag and tags?
---
### Author:  [@hugh](https://meta.discourse.org/u/hugh)
#### Post date: [September 1, 2024, 9:29pm UTC](https://meta.discourse.org/t/discourse-doc-categories/322376/21 "2024-09-01T21:29:07Z")
Thanks for the clarification, @saquetim!
> [@thaidb](#):
>
> How about group tag and tags?
I’m not sure what you mean here - could you clarify a little?
---
### Author:  [@thaidb](https://meta.discourse.org/u/thaidb)
#### Post date: [September 2, 2024, 12:35am UTC](https://meta.discourse.org/t/discourse-doc-categories/322376/22 "2024-09-02T00:35:58Z")
Docs Plugin, we can show tags by group in sidebar to filters.
WIth the new plugin can we do the same?
---
### Author:  [@hugh](https://meta.discourse.org/u/hugh)
#### Post date: [September 2, 2024, 12:47am UTC](https://meta.discourse.org/t/discourse-doc-categories/322376/23 "2024-09-02T00:47:07Z")
> [@thaidb](#):
>
> Docs Plugin, we can show tags by group in sidebar to filters.
> WIth the new plugin can we do the same?
The new plugin cannot do that currently. It may be something we explore in the future, but for now it isn’t something we’re adding to it.
---
### Author:  [@thaidb](https://meta.discourse.org/u/thaidb)
#### Post date: [September 2, 2024, 12:54am UTC](https://meta.discourse.org/t/discourse-doc-categories/322376/24 "2024-09-02T00:54:46Z")
Yes, yes
thank you so much!
---
### Author:  [@dennisjbr](https://meta.discourse.org/u/dennisjbr)
#### Post date: [September 6, 2024, 3:08am UTC](https://meta.discourse.org/t/discourse-doc-categories/322376/25 "2024-09-06T03:08:56Z")
I must be really stupid, but I believe i did everything right, I named a topic to be the index for a category, and set the docs plugin to point to this topic, but i still don’t see a side bar. Is there a step-by-step demo maybe with screenshots? I’m stumped trying ot get a documentation category set up. Thanks!
[Next page](https://meta.discourse.org/t/discourse-doc-categories/322376.md?page=2)