Discourse Docs

[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)]

サムさん、SEOの観点からすると、トピックのrel=canonicalは元のトピックを指すべきではないでしょうか？例えば、Dark/Light Mode Toggle - theme-component - Docs - Discourse Meta → Dark/Light Mode Toggle - theme-component - Discourse Meta のように。この2つのバージョンのページがGoogleのアルゴリズムで互いに食い合わないか気になります。

[sam (Sam Saffron)]

はい、絶対に何かすべきです

[Hyan]

申し訳ありません、@JammyDodgerさん。最近、Specを実行する機会がありませんでした。最近はDiscourse Docs関連の仕事には集中しておらず、他のことをしています。しかし、機会があればお知らせします。

[martyn_thomas]

ハンバーガーメニューの「ドキュメント」の横にあるアイコンを、リンク/チェーンから別のものに変更する方法はありますか？

[martyn_thomas]

このプラグインは、すべてのドキュメントカテゴリを1か所にまとめるのに最適です。これにより、カテゴリリスト（Discourse Category Hiderのおかげで）にもそれらをリストする必要がなくなります。しかし、問題に気づきました。

Docs Plugin/画面内では、既存のドキュメントを編集したり、新しいドキュメントを作成したりできません。つまり、編集したいトピック/ドキュメントを見つけるには元のカテゴリに移動する必要があり、ドキュメントを複数の場所にアクセス可能にする必要があります。

Docsプラグイン内で、トピック/ドキュメントの編集を有効にする方法はありますか（ユーザーが適切なユーザーグループにいる場合）。

[Moin]

@martyn_thomas

編集するには、元のカテゴリに移動してトピック/ドキュメントを見つける必要があります。

「このトピックに関するディスカッションを表示する」リンクを使用して、そのトピックに移動して編集することはできますか？

[digitaldominica]

こんにちは、非常に迷惑な問題が発生しており、その原因がわかりません。

ドキュメントを作成すると、ドキュメント領域に表示され、期待どおりに機能します。しかし、ドキュメントが編集されると、クリック時にドキュメントのリストのトピックのドキュメントレイアウトがデフォルトのDiscourseトピックレイアウトに戻り、実際のドキュメントレイアウトが表示されなくなります。

数分後にトピックドキュメントレイアウトに戻り、期待どおりに表示されることに気づきました。何か原因となっている可能性はありますか？

また、テーマコンポーネント「Topic Thumbnails」を使用しており、ドキュメントのサムネイルモードを「list」に設定していることに注意してください。

[digitaldominica]

問題が見つかりました。どうやら、Topic List Excerpts または Topic lists Thumbnails というテーマコンポーネントを使用すると、クリック可能な href が KB ドキュメントの docs?topic=xxx ではなく、Discourse のトピックページのものになるため、Discourse のトピックにリダイレクトされています。

ドキュメントの URL パスを docs に維持する方法はありますか？ @sam または @david に連絡すべきでしょうか？

[civitas_john (John Chen)]

こんにちは。

ユーザーが最近、些細なデザイン上の問題に気づきました。ブラウザのビューポート幅が狭い場合、次のようなスクリーンショットのように、各ドキュメント投稿のコンテンツがオーバーフローします。

ビューポートが理想よりも狭い場合にサイドバーを自動的に折りたたむ方が良いのではないかと思いますが、サイドバーを折りたたんだとしても、コンテンツはオーバーフローしたままになります。

[Nebthtet]

素晴らしいアドオンをありがとうございます。ただ、1つ質問があります。コンテキストハンバーガーメニューからリンクを削除するオプションはありますか？手動で常に表示されるセクションに追加しました（長文のユーザー作成コンテンツ（記事など）を紹介するためにこの機能を使用したいと考えているため）が、結果として2回表示されるようになりました。

背景が薄い両方のオプションは /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 プラグインをオフにして、テーマを再度オンにしましたが、それらのトピックはまだ表示されません。
よろしくお願いします！