Discourse 文档

[Discourse]

This plugin is being retired in favour of the experimental Doc Categories plugin. We will still support Docs until the new plugin is no longer considered experimental.

	Summary	Discourse Docs provides the ability to find and filter knowledge base topics
	Repository Link	https://github.com/discourse/discourse-docs
	Install Guide	How to install plugins in Discourse

As this is an official plugin maintained by the Discourse team, support, bug, ux, and 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.

 Support  Bug  UX  Feature

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.

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

4. 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

Summary Discourse Docs Card Filter is to be used with the Discourse Docs Plugin and allows you to place “Cards” that act as a clickable filter for quicker filter results upon entering the /docs page by your users. Preview Preview on Discourse Theme Creator Repository Link https://github.com/discourse/discourse-docs-card-filter New to Discourse Themes? Beginner’s guide to using Discourse Themes 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:

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

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

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.

Hosted by us? This plugin is available on all of our hosting plans. Docs | Discourse - Civilized Discussion

Last edited by @hugh 2024-08-27T21:19:54Z

Last checked by @hugh 2024-08-27T04:23:36Z

Check document

Perform check on document:

[Hyan]

您好，Discourse 社区，

我在执行 spec 时遇到了以下错误。我没有更改任何文件。可以忽略此错误吗？

➜  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

[JammyDodger]

@Hyan，你解决这个问题了吗？

[tpetrov (Toni Petrov)]

嘿 Sam，从 SEO 的角度来看，将主题的 rel=canonical 指向原始主题是否有意义？例如，深色/浅色模式切换 - 主题组件 - 文档 - Discourse Meta → 深色/浅色模式切换 - 主题组件 - Discourse Meta？我想知道这两个版本的页面是否会在谷歌的算法中相互蚕食。

[sam (Sam Saffron)]

是的，我们绝对应该在那里做些什么。

[Hyan]

抱歉 @JammyDodger，我最近没机会运行 Spec。我最近不专注于与 Discourse Docs 相关的工作，而是专注于其他事情。但我有机会时会通知你。

[martyn_thomas]

是否有办法将汉堡菜单中“文档”旁边的图标从链接/链条更改为其他图标？

[martyn_thomas]

这个插件很棒，可以将我们所有的文档类别集中在一个地方——无需在“类别”列表中单独列出它们（感谢 Discourse Category Hider）。但是，我们注意到一个问题：

在“文档”插件/屏幕中，您无法编辑现有文档或创建新文档——这意味着您必须转到原始类别才能找到要编辑的主题/文档……这意味着您必须在多个地方访问该文档。

是否有办法在“文档”插件中启用主题/文档编辑（如果用户属于正确的用户组）？

[Moin]

@martyn_thomas

您必须转到原始类别，才能找到要编辑的主题/文档

使用底部的“查看此主题的讨论”链接导航到该主题并进行编辑是否可行？

[digitaldominica]

您好，我遇到了一个非常烦人的问题，但不知道为什么会发生。

当我创建一个文档时，它会进入文档区域并按预期工作，但是如果文档以任何方式被编辑，文档列表的主题文档布局在单击时会切换回默认的 Discourse 主题布局，而不是显示实际的文档布局。

我注意到几分钟后，它会恢复到主题文档布局，看起来就像应该的那样，有什么可能导致这种情况吗？

注意：我还使用了主题组件“Topic Thumbnails”，并将其设置为文档缩略图模式“list”。

[digitaldominica]

找到了问题，显然如果我使用 Topic List Excerpts 或 Topic lists Thumbnails 主题组件，可点击的 href 将是 discourse 主题页面而不是 KB docs?topic=xxx，因此我被重定向到 discourse 主题。\n\n有没有办法在 docs 中将 url 路径保留为 docs @sam，或者我应该联系 @david？

[civitas_john (John Chen)]

您好，

我们的用户最近注意到一个小小的样式问题：当浏览器视口宽度较小时，每个文档帖子的内容会溢出，如下图所示：

我想知道，如果视口宽度不理想，是否最好自动折叠侧边栏；但是，即使我折叠了侧边栏，内容仍然会溢出。

[Nebthtet]

感谢您提供的精彩插件。不过有一个问题：是否有选项可以从上下文汉堡菜单中移除链接？我已手动将其添加到始终可见的部分（因为我们希望使用此功能来展示文章等用户创建的长篇内容），现在它出现了两次：

两个背景较浅的选项都导向 /docs

[Arkshine]

我认为您可以在此处使用一些 CSS 来隐藏它：

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

[Nebthtet]

完美运行！非常感谢！

[rly]

我们能否选择将评论集成到文档页面，而不是链接到帖子然后评论？

[wsxiaolin]

@civitas_john

即使我折叠了侧边栏，内容仍然会溢出。

我在具有相同视口宽度的设备上重新访问了同一个链接。虽然在折叠侧边栏之前仍然存在溢出，但我发现折叠侧边栏后，没有溢出，显示正常且美观。

[supermathie (Michael Brown)]

我感到惊讶，Docs 中默认的搜索顺序不是“相关性”，而是“活动日期”。

是否可以按相关性搜索？

[huynhthai824 (Sora &\)]

我今天在 Docs 分类下发布了一些主题，但这些主题没有显示在 Docs 页面上。我关闭了 docs 插件，然后重新启用了主题，但这些主题仍然没有显示。
谢谢！