I think the confusion and difficulty might be that the Index Topic has to be in a certain format, and this is not completely clearly stated in the documentation (top post)
I had installed this plugin myself, carefully following the instructions, but it wasn’t working in exactly the same way @dennisjbr was experiencing.
It might help to have an example of the Markdown required rather than linking to the Meta example, because the only key rule is that there MUST be a Markdown bulleted/numbered list. The docs say ‘a list’ but the word ‘list’ has an ordinary English usage which includes non-Markdown lists!
This will work as an Index Topic:
* https://meta.discourse.org/t/discourse-doc-categories/322376
* Some Arbitrary Text: https://meta.discourse.org/t/discourse-doc-categories/322376
This will not work:
https://meta.discourse.org/t/discourse-doc-categories/322376
Some Arbitrary Text: https://meta.discourse.org/t/discourse-doc-categories/322376
Beyond this you can use Markdown headings to create sections and use multiple lists, but nothing will appear in the sidebar unless there’s a Markdown list. I appreciate this is a bit obvious and may not have tripped up anyone else, but it did catch me out (stupidly or not) and I’m not new to Discourse, TCs and Plugins.
I have an AI persona for my documentation category. Has there been any thoughts on making an AI persona available for anons? I think at least, in a temporary, anonymous chat DM? Is this even possible?
When you visit a page that is very low in the index (requires scrolling to reach), the main page is also scrolled down to a position somewhere in the middle: for example on this doc item
Actually one should never consider something is “Obvious” when documenting anything. This kind of feedback is vital on any type of project to ensure clarity.
Anything written will typically make sense to the author due to their deep understanding of what they wrote. To others on the other hand it maybe less clear.
I myself dislike terms like “intuitive” as something is only intuitive if one has experiences using something similar.
NOOB here so I apologize in advance! I have been trying to figure this out on my own for a while now but I can’t find a solution anywhere.
I am trying to use this plug-in as a way to organize individuals user projects at the category level.
We are trying to create a forum that will have a bunch of different user projects on it. We originally had them all under category of “projects”, so when someone would click on projects they would see all the subcategory boxes listing out all the individual projects in a pretty UI look and feel (sudo project marketplace).
But by doing that we lose that one level of data organization because the individual projects start as subcategories instead of categories.
I was super excited when I found this plugin because I figured it would be perfect for organizing all the projects at the category level allowing us to have better data organization within the projects.
So I’m now creating individual projects as individual categories (fishing lure, project 2, project 3) and using the doc categories plug into basically create a table of contents of all the projects so that people can click on the new projects category that’s being run by the doc cat plugin and use the drop down menu to navigate through the subcategories and topics that we choose to list in the index topic.
Is there a way to have categories displayed in the middle column so that it resembles the view of “all categories” page in the normal discourse feed?
I want to have it so that when I click on the projects doc category that it lists all the projects on the left in the menu but then also displays them in the boxes in the main feed just like it does normally with subcategories. I was only allowed to put one image on this post so I put the image of the projects in the menu on the left and I would like to have the category boxes showing in the middle where my topic post is showing.
Since relative linking already works. Why not add it and eliminate any work from being needed needlessly? These are internal links after all and this would contribute to discourse’s parity as internal links also works variety of TC & plugins.
Thanks Hugh!
What you guys are doing with the subcats is on the right path, but I mainly wanted to get the UI to show Categories in the boxes in the middle column like it does with subcats.
I ended up finding and installing the sub-sub-cat plug-in. So now I’m using that plug-in to help me group subcategories so they are really acting as ‘categories’ because we have two levels of data distribution below them sub-sub-cats, and topics.
This met my main goal of increasing the amount of data distribution and organization levels within our user projects. So now I’m using the sub sub categories along with the plug-in to get the best of both worlds at the stub category level.
I was trying to create the project category with just the duck categories plug-in, but we didn’t like the UI of having just a menu off the left and nothing in the middle for the user to browse. So, I wanted to get the (projects which are categories) to display within a Category (all projects) like the subcats can do normally. (my pic in the last post of my mockup)
What is the advantage of this plugin over the legacy docs plugin?
In the legacy plugin, I can have docs in any category, given that I maintain tags. Now it seems that all documentation topics must live under a single category. Is that correct? In this case, it’s kinda losing context, since some (existing) documentation might be affected to specific groups/categories (e.g., only available to Staff).
Could you please clarify the differences between the two approaches, why did you chose this approach, and how you intend to close the gap between the legacy plugin and the new one?
OT comment on "callouts"
HedgeDoc uses the following Markdown extension to support callouts (they call it alert areas):
### Alert Area
:::success
Yes :tada:
:::
:::info
This is a message :mega:
:::
:::warning
Watch out :zap:
:::
:::danger
Oh No! :fire:
:::
will display (this would be pretty easy to style with CSS given a class).
OT comment on laziness and AI
Can you imagine the excess energy and water consumed for just three lines of Markdown you could have copy-pasted manually?
OT comment on relative vs. absolute URLs
Actually, copy-pasting topic URLs is easier, and if you change domains, you’d probably export/import topics, and Discourse would replace the domain for you.
After experimenting a bit, here are my (temporary) conclusions:
A top-level Documentation category enables using sub-categories to change the documentation sidebar index (e.g., “Install Ruby” appears under “How-to Guides” in Documentation - petites singularités, but under “Tips & Hints” at Sysadmin - petites singularités) to provide a nice structure (see Documentation here, displaying subcategories as boxes)
Documentation topics can be anywhere in the forum, including in private spaces – although the documentation index then reveals their existence
The sidebar is currently unstable:
sometimes it displays URLs, sometimes the title
sometimes only prefixed text
when logged out, it may miss some indexed topics
When migrating from the legacy docs plugin, the docs link must be recreated in the custom section of the sidebar (but could be auto-generated changing /docs to the documentation category in the plugin setting, or creating/changing the /docs permalink to link to that category)
The “Back to forum” link feels weird, because documentation topics remain forum topics: we’re still there reading docs!
Filtering does not yet take into account (sub-)category names where the documentation topic belongs.
I also think this “filter” search box would be much more effective if it’s just a custom search query in the current category by default (instead of asking this if there is no result). The titles are very short, so in most cases there won’t be a hit to anything a non-familiar user would type there.
Took me a while to figure out that the sidebar wasn’t appearing because for some reason the setting for the navigation menu was set to “header dropdown” instead of “Sidebar”. For those who also couldn’t get the sidebar to appear, that might be the reason.
I can’t see any setting to enable/disable that and it just doesn’t seem to want to appear unfortunately.
If anyone has any ideas, I’d appreciate the insight.
Thanks.
The lack of filtering by tag greatly diminishes the usefulness of the plugin. In a community where one document can apply to multiple categories, filtering by tag is essential.
For example, a document named Landing Gear Assembly applies to multiple aircraft models and can also contain multiple tags. Finding the right one is very easy with tag filtering.
If you have to pick one category for the document, what do you do when that same document should also be in several other categories?
Tags were the automatic index that now has to be manually created and maintained.
(this would be pretty easy to style with CSS given a class).
