Discourse Doc Categories

Love the plug in

Is it possible to add support to group headings into sections to help with layout. Something like H1 = Section header, H2 - group/folder header

I’ve tried to mock it up a little:

We are a makerspace with lots of Tool Areas, across different rooms. It would be great to have the Tool groups sectioned off by room

4 Likes

Could I use an external link here? And use _blank for open new tab?

You can start with an optional brief description of the category.

## Test external
* Google: https://google.com

## 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
1 Like

Any unsupported installations will typically receive a link to unsupported installations. As a disclaimer as any issues could be in part related.

Plugins, themes, and theme components typically will have a file regarding version compatibility file

See below

Opening this file will give important version compat notes. Others may have it within the description. Ie Category Moderators enhance plugin has disclaimer of only supporting stable branch.

Pavilion gives recommended discourse update frequency to ensure they have time to update their add-ons.

2 Likes

Does this work for subcategories? I have a site with 6 core categories but want documentation for each category, as well as discussion. Not quite sure how best to achieve this.

It does. You can see it here in Documentation. The main category is basically a table of contents to the subcategories.

3 Likes

Just came across this and have a couple of questions please: How can we install it on our cloud-hosted site? And how much longer will the old Docs be around, do you think?

1 Like

We don’t have a timeline for completely removing the old plugin just yet, but it is no longer being actively developed. Once we have made some decisions about this, we’ll post an announcement about it to let everyone know!

Since this plugin is still experimental, it isn’t available on our hosting, but we’re currently discussing this internally and seeing if we can make this plugin available. We’ll circle back here once we have come to a conclusion there.

4 Likes

I’m gonna just add this for others who may find it confusing, like I was, what the plugin really does.

With all the settings, and the index topic, etc, it can feel overwhelming, on top of trying to understand what can be done, how it can be used, etc. At least, I was a bit confused until I figured out a way to understand it (if I’m missing something here, feel free to share it).

So basically the way I see it is: create your categories the way you want them and then this plugin just removes the default sidebar (with the sections for categories, tags, etc), and replaces it with a list of sections and links inside those sections to topics, categories, external links, etc. It’s just easier for me to look at it that way. It’s something more focused on customizing the sidebar when a particular category is visited. Something like: when category A is visited, replace the default sidebar with that custom sidebar provided by the index topic. Simple.

5 Likes

Feature Request:

Add support for “Discourse Icon” to render in Sidebar also bbcode color
& Emoji support.

2 Likes

This good suggestion would be better as a linked topic in Feature and tagged doc-categories

1 Like

Added thanks

1 Like

9 posts were split to a new topic: Discourse Docs Plugin – Topics Not Updating in Docs Page

I wonder how to make the sidebar index on Docs more visible on mobile, because users don’t see the topics until pressing the hamburger icon.

It’s wonderful on desktop; unfortunately, the majority use their smartphones.

1 Like

There isn’t too many options, or I would say there isn’t any options at all. Mobiles just don’t have enough space.

That is one reason why I’m considering leaving docs totally. Of my users aroung 95% are using mobiles, and they use sidebar very rarely or not at all. So curating doc-menu is quite time consuming and I don’t think that time/benefit ratio is in balance :smirking_face:

1 Like

I think that moving the hamburger icon to the left (like in desktop) should improve a little the user experience.

Docs are really powerful, I don’t want to disable it but it’s almost no used by our users because the indexs are hidden (!)

2 Likes

This Theme component maybe of interest

Alright, I’ve read through this whole discussion and I have a few questions. I get that this page’s structure is created by this page, but then you also need an index page for each sub-category as well? The index for this page, must be enormous… or any of the other ones with a ton of articles.

How hard would it be to implement an xwiki style of layout for pages that are part of a Discourse site’s documentation. The UI is simple enough, you check the box on page creation stating that this page is documentation. Now it simply asks you what the parent is. No parent? It’s a top level subject. You set a parent, the page shows up under that subject/category. This completely eliminates the requirement to manually maintain index pages. They look like a lot of extra work that shouldn’t be necessary. And easy to overlook adding things as they’re created.

If you go to https://checkin.technospider.com and disclose some of the items in the sidebar, you can see how the nesting works in a real world example. That entire sidebar is dynamically generated simply by nesting pages under other pages (parent/child relationship). This site only has about 150 pages on it but it would have taken me twice as long to get it completed if I had to make indexes to create all of that.

And that brings me to a UI/UX issue with how the Docs sidebar is laid out. Once you click away from the main page, you lose the initial list of categories. You should have a way to go back on the page somewhere.
Each of your 8 main areas should have disclosure triangles on them so whether you click the box on the main page, or the name in the sidebar, it just drops down and you don’t lose the ability to directly click on another of the main areas.
You have a breadcrumb on each end article, but even that is missing from the 8 categories. Clicking ‘remove filter’ from the subcategories at the top of the page takes me back, but that’s very unintuitive. And you can do some weird things by playing with the filters, for example, the nice green banner disappears if you click ‘no subcategories’

2 Likes

Yes, that’s for site management topics, the index page is here. (index is a tag that reveals all the index pages)

Agree it must’ve taken a good bit of work to corral all the page links and put them nicely in categories with labels. But the result is so darn nice and usable!

2 Likes

It definitely looks nice, but as I stated, there’s some usability issues as far as navigation is concerned.
And if the work can be eliminated that seems like a win for everyone.

I’m not dogging on the work done, it looks very nice and since I can’t code to save my life I can’t even begin to appreciate how much work went into it, or how much more work my suggestions would be.

It’s good for minimum docs, but a lot of markup is missing that I used on the wiki I linked to. Unless I’m just missing it. I’m still pretty new to Discourse.

For example, I can’t find a way to make info/warning/error boxes.

Out of curiosity, are there any thoughts on implementing this feature request? It feels particularly useful alongside this plugin:

A common complaint we have in our community regarding “wiki posts” is that the author of the post has concerns that they can be made to look like they’re saying something that they don’t necessarily agree with.

2 Likes