Discourse-docs: Documentation Management Plugin

Summary: Find and filter knowledge base topics

:link: GitHub: https://github.com/discourse/discourse-docs
:arrow_right: Install: Follow the plugin installation guide.

Features

The Docs plugin is a continuation of development on the Knowledge Explorer Theme Component. You can see it in action at https://meta.discourse.org/docs.

In essence, Docs allows for easier surfacing of knowledge-base style topics across a defined set of categories and/or tags.

Filter the list down by tags, search via the search bar, and click on topics to see the first post – all without leaving the context of the knowledge explorer.

Need to find a knowledge base topic from somewhere else in Discourse? Use the new search helper: in:kb.

Configuration

  1. Install the plugin following these instructions.
  2. Enable the plugin by turning on the docs enabled setting.
  3. Add categories and tags to the docs categories and docs tags settings.
  4. Find the Docs link in the hamburger menu.
    Screen Shot 2021-03-01 at 12.49.14 PM
  5. Profit with easier access to knowledge!

Helpful Pairings

CHANGELOG

  • 2021-01-18T06:00:00Z Rename to discourse-docs
  • 2021-01-13T06:00:00Z Add topic title and category to browser title
  • 2020-10-01T05:00:00Z Added onebox support

TODO

63 Likes

This plugin is the primary reason why I chose to use Discourse for my project, so thanks very much!

However, it has a significant shortcoming for my (and, seemingly, most) application - there is no ability to sort the topics in a custom order. This is crucial for my docs, where the Topics follow a very particular order for configuring the software.

The best solutions seem to be:

  1. ability to sort by Title, and prepend 1., 2., 3., etc… to the titles. Though, this makes it very difficult to insert articles in the middle of a list. This feature request for Alphabetical sorting seems to have been rejected, and also erroneously stated that Docs has this capability. Feature request: Sort display of topics Alphabetically - feature - Discourse Meta

  2. Some sort of re-order mechanism, like with the Reorder Categories tool

Is there anything you can think of - even if it requires custom work - to make this possible?

Thanks!

4 Likes

I just realized that we can sort by title by clicking on the column header. It wasn’t at all obvious because there is no arrow shown by default to indicate that the columns are sortable

So, I’d suggest making the default view have a sorting arrow on Activity.

I’ll probably edit the code to remove the activity sorting and just only sort Ascending on the Title, using numbered prefixes for my articles.

Still, I think it would be very cool to have a Re-order mechanism

3 Likes

Hi All,

Does any one know how I can make the Layouts Plugin (Layouts - Pavilion) show on Discourse Docs pages

You can see an example of the side bar on any page on https://community.cyanlabs.net and hen that it’s missing here Docs - CyanLabs Official Community

1 Like

@Fma965 I don’t know, but I’m eager for someone to respond! I wasn’t aware of that plugin but would now love to use it with Docs.

2 Likes

I might take a look at the code my self tomorrow, ruby etc isn’t my language of choice though.

Hey @Nick_Chomey,

Glad you like the plugin. More details on the above discussion here:

3 Likes

I’d like to only allow for sorting Docs by title, rather than also by activity. I see that in lib\docs\query.rb, i can edit lines 80-92 and 147-156 to remove sort by activity, but I will lose this upon updating the plugin. I could disable updates, or reapply this change when there are updates, but neither seem like a good solution.

Is there any possibility of adding settings to allow us to select which types of sorting are available? I would submit a pull request, but I don’t know how to achieve such a thing.

1 Like

Hey guys

we are currently testing the plugin with our internal mod and staff documentation. And later we will roll it out for public guides as well.

Two questions:

  1. Is there any way to have pinned topics actually be pinned at the top top of the topic list in /docs? That way we can add a topic such as “New here? Please start with this” to the top to guide the users.

  2. Is there any additional sorting feature and setting up a default order for topics planned?

1 Like

I figured this out and have a fork of the Discourse Docs repo with the changes here: GitHub - nickchomey/discourse-docs

It removes the ability to sort by activity, and also defaults the category sort to alpha rather than by numeric count. Obviously this would all be better if it could be adjusted with settings, but I don’t have any clue as to how to do that.

1 Like

This is awesome!

@justin any chance such a sorting feature will be added to the docs plugin in the future?

1 Like