Discourse Doc Categories

:discourse2: Summary Discourse Doc Categories provides the ability for particular categories to be set aside for documentation, enabling additional features for them.
:hammer_and_wrench: Repository Link https://github.com/discourse/discourse-doc-categories
:open_book: Install Guide How to install plugins in Discourse

:warning: 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 :wrench: 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:

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:

:eyes: 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 documentPerform check on document:
20 Likes

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 :smiley:)

4 Likes

I would guess component discourse-doc-sidebar (did I remember the name right) isn’t needed anymore?

2 Likes

Yes - the component that was originally built for the new documentation sidebar has been moved to this plugin.

2 Likes

I guess this doesn’t work with tags anymore? :slight_smile:

2 Likes

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!

1 Like

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. :thinking:

3 Likes

Something like the footnote feature, but globally keyword triggered would be epic for such a feature.

2 Likes

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 :smiley:

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 :stuck_out_tongue: I was exploring moving my docs to Quartz with content managed in Obsidian.

1 Like

Any chance, it will be compatible with 3.3 stable?

1 Like

Yes, this is fully compatible with Discourse 3.3 :slight_smile:

No, it’s not:

/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

3 Likes

Emoji rendering in the titles & items in the sidebar would be awesome!

2 Likes

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.

5 Likes

How about group tag and tags?

1 Like

Thanks for the clarification, @saquetim!

I’m not sure what you mean here - could you clarify a little?

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.

1 Like

Yes, yes
thank you so much!

1 Like

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!

1 Like