# Discourse Docs

**URL:** https://meta.discourse.org/t/discourse-docs/130172
**Category:** Plugin
**Tags:** official, docs, end-of-life
**Created:** [October 3, 2019, 7:10pm UTC](https://meta.discourse.org/t/discourse-docs/130172 "2019-10-03T19:10:37Z")
**Posts on this page:** 20
**Page:** 1

<div class="post-metadata">

### Author: ![Discourse](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/discourse/32/148734_2.png) [@Discourse](https://meta.discourse.org/u/Discourse)
#### Post date: [October 3, 2019, 7:10pm UTC](https://meta.discourse.org/t/discourse-docs/130172/1 "2019-10-03T19:10:37Z")

</div>

> ⚠ This plugin is being retired in favour of the experimental [Doc Categories plugin](https://meta.discourse.org/t/discourse-doc-categories/322376). We will still support Docs until the new plugin is no longer considered experimental.

| | | |
| --- | --- | --- |
| :discourse2: | **Summary** | **Discourse Docs** provides the ability to find and filter knowledge base topics |
| 🛠 | **Repository Link** | [https://github.com/discourse/discourse-docs](https://github.com/discourse/discourse-docs) |
| 📖 | **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. 👍
> 
> [❓&nbsp; **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=docs "Ask for support on configuring and using Discourse Docs") [🐛&nbsp; **Bug**](https://meta.discourse.org/new-topic?category_id=1&tags=docs "A bug report means something is broken, preventing normal/typical use of the plugin") [👀&nbsp; **UX**](https://meta.discourse.org/new-topic?category_id=9&tags=docs "Discussion about the user interface of Discourse Docs, and how features are presented (including language and UI elements)") [💡&nbsp; **Feature**](https://meta.discourse.org/new-topic?category_id=2&tags=docs "Discussion about how existing Discourse Docs features can be improved or enhanced, and how proposed new features could work")

### Features

The Discourse Docs plugin is a powerful tool that transforms your Discourse forum into a community-powered knowledge base. It provides a dedicated Docs section where users can create, update, and curate documentation. This plugin features a Docs button that allows easy access to this section. It’s a great way to leverage the collective knowledge of your community and provide a centralized resource for important information.

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

 ![docs page](https://global.discourse-cdn.com/meta/original/3X/b/f/bf89c5aad3835d1b4da4b5cb61c40a4e9573b7d5.png)

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.

 ![filter topics](https://global.discourse-cdn.com/meta/original/3X/1/4/14baef7c76d52ca76f2dd6ce125fddaa1b39564c.png)

 ![search topics](https://global.discourse-cdn.com/meta/original/3X/c/1/c192ebcaf525714d81ef65471cca84617c5572ef.png)

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

 ![in:kb](https://global.discourse-cdn.com/meta/original/3X/1/b/1b2cd1522b6dd11a041579a36a9e817e7f41a85d.png)

### Configuration

1. Enable the plugin by turning on the `docs enabled` setting.

2. Add categories and tags to the `docs categories` and `docs tags` settings.

3. Find the Docs link in the navigation menu.

 ![Screen Shot 2021-03-01 at 12.49.14 PM](https://global.discourse-cdn.com/meta/original/3X/a/e/ae2abc6f1ec75e18029b699c9e06f3d199b775ca.png)

1. Profit with easier access to knowledge!

### Settings

| Name | Description |
| --- | --- |
| docs enabled | Enable the Docs Plugin |
| docs categories | A list of category slugs to include in docs |
| show tags by group | Organize tags using Tag Groups. Create groups to categorize related tags. |
| docs tag groups | The Tag Groups used to show tags by group |
| docs tags | A list of tags to include in docs |
| docs add solved filter | Adds a filter for solved topics – requires Discourse Solved to be installed and enabled |
| docs add to top menu | Adds a link to the top menu to navigate to the Docs view |
| docs add search menu tip | Adds the tip “in:docs” to the search menu random tips |

### Helpful Pairings

> [@Discourse Docs Card Filter](https://meta.discourse.org/t/discourse-docs-card-filter-component/187947):
>
> discourse2Summary Discourse Docs Card Filter is to be used with the [Discourse Docs Plugin](https://github.com/discourse/discourse-docs) and allows you to place “Cards” that act as a clickable filter for quicker filter results upon entering the /docs page by your users.eyeglassesPreview [Preview on Discourse Theme Creator](https://discourse.theme-creator.io/theme/Discourse/docs-card-filter)hammer_and_wrenchRepository Link [https://github.com/discourse/discourse-docs-card-filter](https://github.com/discourse/discourse-docs-card-filter)open_bookNew to Discourse Themes? [Beginner’s guide to using Discourse Themes](https://meta.discourse.org/t/beginners-guide-to-using-discourse-themes/91966) Install this theme comp…

### Renaming the `/docs` path

If you have access to your server you can change the path of your `/docs` link by adding a `DISCOURSE_DOCS_PATH:` environment variable to your `app.yml`:

 ![discourse_docs_path](https://global.discourse-cdn.com/meta/original/4X/d/b/3/db3182ef270516f69f58df114549a64cf02e2e3e.png)

For the change to take effect you can either `./launcher rebuild app` or, as it’s an environment variable, you can `./launcher destroy app && ./launcher start app` to minimise downtime. There’s a little more info on that here - [Set Environmental Variables](https://meta.discourse.org/t/set-environmental-variables/270832)

You may also want to change the site display text as well to match. You can search for all instances of ‘docs’ from your `/admin/customize/site_texts` page, but the main ones would be:

- js.docs.title
- js.sidebar.docs\_link\_text

 ![cake recipe display text](https://global.discourse-cdn.com/meta/original/4X/9/3/4/93419f9c92e460c3cde66b274243c32ab6d33eba.png)

> :discourse2: **Hosted by us?** Renaming the `/docs` path is only available on our Enterprise plan. Please contact us if you’d like to learn more.

### Development History

The Docs plugin was a continuation from the [Knowledge Explorer Theme Component](https://meta.discourse.org/t/knowledge-base-theme-component/121898).

> Last edited by @HAWK 2026-07-06T22:06:30Z
> 
> Last checked by @hugh 2024-08-27T04:23:36Z
> 
> > **Check document**
> >
> > Perform check on document:

---

<div class="post-metadata">

### Author: ![Hyan](https://avatars.discourse-cdn.com/v4/letter/h/5fc32e/32.png) [@Hyan](https://meta.discourse.org/u/Hyan)
#### Post date: [September 25, 2023, 9:52am UTC](https://meta.discourse.org/t/discourse-docs/130172/341 "2023-09-25T09:52:37Z")

</div>

Hi Discourse community,

I got below error when executing the spec. I didn’t change any files. Can I ignore this error?

```plaintext
➜ discourse git:(main) ✗ LOAD_PLUGINS=1 bundle exec rspec plugins/discourse-docs/spec

Randomized with seed 57815
...................................F

Failures:

  1) Discourse Docs | Index topic excerpts when the theme modifier serialize_topic_excerpts is true shows the excerpts
     Failure/Error: expect(page).to have_css(".topic-excerpt", text: topic_1.excerpt)
       expected to find css ".topic-excerpt" but there were no matches

     [Screenshot Image]: /xxxx/discourse/discourse/tmp/capybara/failures_r_spec_example_groups_discourse_docs_index_topic_excerpts_when_the_theme_modifier_serialize_topic_excerpts_is_true_shows_the_excerpts_460.png

     ~~~~~~~JS LOGS~~~~~~~
     ~~~~~END JS LOGS~~~~~

     # ./plugins/discourse-docs/spec/system/docs_index_spec.rb:52:in `block (4 levels) in <main>'
     # ./spec/rails_helper.rb:469:in `block (2 levels) in <top (required)>'

Finished in 13.16 seconds (files took 2.79 seconds to load)
36 examples, 1 failure

Failed examples:

rspec ./plugins/discourse-docs/spec/system/docs_index_spec.rb:50 # Discourse Docs | Index topic excerpts when the theme modifier serialize_topic_excerpts is true shows the excerpts

Randomized with seed 57815

```

---

<div class="post-metadata">

### Author: ![JammyDodger](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/jammydodger/32/254611_2.png) [@JammyDodger](https://meta.discourse.org/u/JammyDodger)
#### Post date: [November 22, 2023, 7:34pm UTC](https://meta.discourse.org/t/discourse-docs/130172/345 "2023-11-22T19:34:50Z")

</div>

Did you manage to resolve this @Hyan?

---

<div class="post-metadata">

### Author: ![JammyDodger](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/jammydodger/32/254611_2.png) [@JammyDodger](https://meta.discourse.org/u/JammyDodger)
#### Post date: [November 25, 2023, 1:43pm UTC](https://meta.discourse.org/t/discourse-docs/130172/346 "2023-11-25T13:43:25Z")

</div>

3 posts were split to a new topic: [How can I get a table of contents for my docs?](https://meta.discourse.org/t/how-can-i-get-a-table-of-contents-for-my-docs/286586)

---

<div class="post-metadata">

### Author: ![tpetrov](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/tpetrov/32/164643_2.png) [@tpetrov](https://meta.discourse.org/u/tpetrov)
#### Post date: [November 28, 2023, 9:19am UTC](https://meta.discourse.org/t/discourse-docs/130172/347 "2023-11-28T09:19:35Z")

</div>

Hey Sam, wouldn’t it make sense from SEO perspective the rel=canonical of topics to point to the original topic? E.g. [Dark/Light Mode Toggle - theme-component - Docs - Discourse Meta](https://meta.discourse.org/docs?topic=215585) → [Dark/Light Mode Toggle - theme-component - Discourse Meta](https://meta.discourse.org/t/dark-light-mode-toggle/215585)? I wonder if the two versions of the page don’t cannibalize each other in google’s algorithms.

---

<div class="post-metadata">

### Author: ![sam](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/sam/32/102149_2.png) [@sam](https://meta.discourse.org/u/sam)
#### Post date: [November 28, 2023, 9:31am UTC](https://meta.discourse.org/t/discourse-docs/130172/348 "2023-11-28T09:31:38Z")

</div>

Yes, absolutely we should do something there

---

<div class="post-metadata">

### Author: ![Hyan](https://avatars.discourse-cdn.com/v4/letter/h/5fc32e/32.png) [@Hyan](https://meta.discourse.org/u/Hyan)
#### Post date: [November 29, 2023, 12:49pm UTC](https://meta.discourse.org/t/discourse-docs/130172/349 "2023-11-29T12:49:52Z")

</div>

Sorry @JammyDodger I haven’t got a chance to run the Spec these days. I don’t focus on the work related to Discourse Docs but other stuff these days. But will let you know when I get any chance.

---

<div class="post-metadata">

### Author: ![martyn\_thomas](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/martyn_thomas/32/344874_2.png) [@martyn\_thomas](https://meta.discourse.org/u/martyn_thomas)
#### Post date: [December 7, 2023, 9:29pm UTC](https://meta.discourse.org/t/discourse-docs/130172/350 "2023-12-07T21:29:49Z")

</div>

Is there a way to change the icon next to the Docs in the Hamburger Menu from the link/chain to something else?

---

<div class="post-metadata">

### Author: ![martyn\_thomas](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/martyn_thomas/32/344874_2.png) [@martyn\_thomas](https://meta.discourse.org/u/martyn_thomas)
#### Post date: [December 13, 2023, 9:11pm UTC](https://meta.discourse.org/t/discourse-docs/130172/351 "2023-12-13T21:11:58Z")

</div>

This plugin is great for having all our document categories all in one place - removing the need for them to also be listed in the Categories list (thanks Discourse Category Hider). However we have noticed an issue:

Within the Docs Plugin/screen you cannot edit existing documents or create new ones - meaning you have to go to the original category, to find the topic/document to edit it…meaning you have to have the document accessible in more than one place.

Is there a way to enable topic/document editing (if the user is in the right User Group) within the Docs plugin?

---

<div class="post-metadata">

### Author: ![Moin](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/moin/32/554653_2.png) [@Moin](https://meta.discourse.org/u/Moin)
#### Post date: [December 13, 2023, 9:55pm UTC](https://meta.discourse.org/t/discourse-docs/130172/352 "2023-12-13T21:55:28Z")

</div>

> [@martyn\_thomas](#):
>
> you have to go to the original category, to find the topic/document to edit it

Does it work to use the “view the discussion on this topic” link at the bottom to navigate to that topic and edit it?

---

<div class="post-metadata">

### Author: ![digitaldominica](https://avatars.discourse-cdn.com/v4/letter/d/97f17d/32.png) [@digitaldominica](https://meta.discourse.org/u/digitaldominica)
#### Post date: [December 26, 2023, 12:11pm UTC](https://meta.discourse.org/t/discourse-docs/130172/353 "2023-12-26T12:11:16Z")

</div>

Hi, I have an issue that’s real annoying and I do not know why it’s happening.

When i create a doc it goes to the document area and works as its suppose to, however if the document is edited in anyway the docs listing topic document layout switches back to the default discourse topic layout upon click and not show the actual document layout.

I’ve noticed after a few minutes it reverts back to the topic document layout and looks as its supposed to, is there anything that could be causing this?

Note i also use the theme component “Topic Thumbnails” and set to docs thumbnail mode “list”

---

<div class="post-metadata">

### Author: ![digitaldominica](https://avatars.discourse-cdn.com/v4/letter/d/97f17d/32.png) [@digitaldominica](https://meta.discourse.org/u/digitaldominica)
#### Post date: [December 26, 2023, 7:40pm UTC](https://meta.discourse.org/t/discourse-docs/130172/354 "2023-12-26T19:40:13Z")

</div>

Found the issue, apparently if I use [Topic List Excerpts](https://meta.discourse.org/t/topic-list-excerpts/151520) or [Topic lists Thumbnails](https://meta.discourse.org/t/topic-list-thumbnails/150602) theme component the clickable href is for the discourse topic page and not the KB docs?topic=xxx so I’m being redirected to discourse topics.

Is there a way to maintain the url path on the docs to docs @sam or should reach out to @david ?

---

<div class="post-metadata">

### Author: ![civitas\_john](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/civitas_john/32/357055_2.png) [@civitas\_john](https://meta.discourse.org/u/civitas_john)
#### Post date: [January 23, 2024, 2:27am UTC](https://meta.discourse.org/t/discourse-docs/130172/355 "2024-01-23T02:27:50Z")

</div>

Hi,

Our users recently noticed a minor stylish issue: when the browser has less viewport width, the content of each docs post will overflow, such as in the following screenshot:

 ![A3F1D2BD9EDC394D8DFBFD10A7EEB819](https://global.discourse-cdn.com/meta/original/4X/4/e/8/4e8f4d3637341f9fb4fa0c0da18c6f83fe24ec04.jpeg)

I wonder if it would be better to automatically collapse the sidebar, if the viewport is less than ideal; however, even if I collapsed the sidebar, the content would still overflow.

---

<div class="post-metadata">

### Author: ![Nebthtet](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/nebthtet/32/352272_2.png) [@Nebthtet](https://meta.discourse.org/u/Nebthtet)
#### Post date: [February 2, 2024, 11:25pm UTC](https://meta.discourse.org/t/discourse-docs/130172/356 "2024-02-02T23:25:26Z")

</div>

Thanks for the wonderful addon. One question though: is there an option to remove the link from the context hamburger menu? I added it manually in the always-visible section (as we want to use this functionality to showcase longform user-created content like articles etc) and now ended up with it showing up twice:

Both options with lighter background lead to /docs

 ![image](https://global.discourse-cdn.com/meta/original/4X/c/2/a/c2a739fe07fe41a8a48e76fc6fb47f2c2e20714e.png)

---

<div class="post-metadata">

### Author: ![Arkshine](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/arkshine/32/298682_2.png) [@Arkshine](https://meta.discourse.org/u/Arkshine)
#### Post date: [February 3, 2024, 2:05am UTC](https://meta.discourse.org/t/discourse-docs/130172/357 "2024-02-03T02:05:08Z")

</div>

I think you can hide it with some CSS here:

```css
.sidebar-section-link-wrapper[data-list-item-name="docs"] {
    display: none;
}

```

---

<div class="post-metadata">

### Author: ![Nebthtet](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/nebthtet/32/352272_2.png) [@Nebthtet](https://meta.discourse.org/u/Nebthtet)
#### Post date: [February 4, 2024, 3:12am UTC](https://meta.discourse.org/t/discourse-docs/130172/358 "2024-02-04T03:12:21Z")

</div>

Worked perfectly! Thank you very much!

---

<div class="post-metadata">

### Author: ![rly](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/rly/32/361778_2.png) [@rly](https://meta.discourse.org/u/rly)
#### Post date: [February 8, 2024, 5:16pm UTC](https://meta.discourse.org/t/discourse-docs/130172/359 "2024-02-08T17:16:44Z")

</div>

any chance we can have an option to integrate the comments on a docs page instead of linking to the post and then being able to comment?

---

<div class="post-metadata">

### Author: ![wsxiaolin](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/wsxiaolin/32/374969_2.png) [@wsxiaolin](https://meta.discourse.org/u/wsxiaolin)
#### Post date: [March 17, 2024, 2:53pm UTC](https://meta.discourse.org/t/discourse-docs/130172/360 "2024-03-17T14:53:15Z")

</div>

> [@civitas\_john](#):
>
> 即使我折叠了侧边栏，内容仍然会溢出。

I revisited the same link on a device with the same viewport width. While there was still overflow before collapsing the sidebar, I found that after collapsing it, there is no overflow, and the display is normal and aesthetically pleasing.

 ![Screenshot_20240317_224848](https://global.discourse-cdn.com/meta/original/4X/c/9/c/c9cbbacaa76e22995a81578f1c744c625e28a07f.jpeg)

---

<div class="post-metadata">

### Author: ![supermathie](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/supermathie/32/507518_2.png) [@supermathie](https://meta.discourse.org/u/supermathie)
#### Post date: [April 26, 2024, 11:50pm UTC](https://meta.discourse.org/t/discourse-docs/130172/361 "2024-04-26T23:50:40Z")

</div>

I’m [surprised](https://meta.discourse.org/t/discourse-needs-better-search/305583/13) that the default search order in Docs is not “Relevance” but “Activity Date”.

Is it possible to search by relevance?

---

<div class="post-metadata">

### Author: ![thaidb](https://sea3.discourse-cdn.com/meta/user_avatar/meta.discourse.org/thaidb/32/68488_2.png) [@thaidb](https://meta.discourse.org/u/thaidb)
#### Post date: [May 20, 2024, 5:53pm UTC](https://meta.discourse.org/t/discourse-docs/130172/362 "2024-05-20T17:53:58Z")

</div>

Today i post some topic on Docs Category, but those topic not Display in Docs page. I turn off docs plugin and turn theme back on again But those topics untill Not display.  
Thank you!

[Next page](https://meta.discourse.org/t/discourse-docs/130172.md?page=2)
