مستندات 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،

لقد واجهت الخطأ التالي عند تنفيذ المواصفات. لم أقم بتغيير أي ملفات. هل يمكنني تجاهل هذا الخطأ؟

➜ 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 للمواضيع إلى الموضوع الأصلي؟ على سبيل المثال، تبديل الوضع الداكن/الفاتح - مكون سمة - المستندات - Discourse Meta → تبديل الوضع الداكن/الفاتح - مكون سمة - Discourse Meta؟ أتساءل عما إذا كان الإصداران من الصفحة لا يتنافسان على بعضهما البعض في خوارزميات جوجل.

[sam (Sam Saffron)]

نعم، بالتأكيد يجب أن نفعل شيئًا هناك

[Hyan]

عذرًا @JammyDodger لم أحصل على فرصة لتشغيل المواصفات هذه الأيام. لا أركز على العمل المتعلق بوثائق Discourse ولكن على أمور أخرى هذه الأيام. لكن سأعلمك عندما أحصل على أي فرصة.

[martyn_thomas]

هل هناك طريقة لتغيير الأيقونة بجوار المستندات في قائمة الهامبرغر من الرابط/السلسلة إلى شيء آخر؟

[martyn_thomas]

هذا المكون الإضافي رائع لوجود جميع فئات مستنداتنا في مكان واحد - مما يزيل الحاجة إلى إدراجها أيضًا في قائمة الفئات (شكرًا لـ Discourse Category Hider). ومع ذلك، لاحظنا مشكلة:

ضمن المكون الإضافي/شاشة المستندات، لا يمكنك تعديل المستندات الموجودة أو إنشاء مستندات جديدة - مما يعني أنه يتعين عليك الانتقال إلى الفئة الأصلية للعثور على الموضوع/المستند لتعديله… مما يعني أنه يتعين عليك إتاحة المستند في أكثر من مكان واحد.

هل هناك طريقة لتمكين تعديل الموضوع/المستند (إذا كان المستخدم في مجموعة المستخدمين الصحيحة) ضمن المكون الإضافي للمستندات؟

[Moin]

@martyn_thomas

عليك الذهاب إلى الفئة الأصلية للعثور على الموضوع/المستند لتعديله

هل يعمل استخدام رابط “عرض المناقشة حول هذا الموضوع” في الأسفل للانتقال إلى هذا الموضوع وتعديله؟

[digitaldominica]

مرحباً، لدي مشكلة مزعجة حقًا ولا أعرف سبب حدوثها.

عندما أقوم بإنشاء مستند، فإنه ينتقل إلى منطقة المستندات ويعمل كما هو مفترض، ولكن إذا تم تعديل المستند بأي شكل من الأشكال، فإن تخطيط مستند قائمة المستندات يعود إلى تخطيط موضوع المناقشة الافتراضي عند النقر عليه ولا يُظهر تخطيط المستند الفعلي.

لاحظت أنه بعد بضع دقائق يعود إلى تخطيط مستند المناقشة ويبدو كما هو مفترض، هل هناك أي شيء يمكن أن يسبب هذا؟

ملاحظة: أستخدم أيضًا مكون السمة “مصغرات المناقشة” وتم تعيينه على وضع مصغرات المستندات “قائمة”.

[digitaldominica]

تم العثور على المشكلة، يبدو أنه إذا استخدمت مكون السمة Topic List Excerpts أو Topic lists Thumbnails فإن الرابط القابل للنقر يكون لصفحة موضوع discourse وليس لـ docs?topic=xxx، لذلك يتم إعادة توجيهي إلى مواضيع discourse.

هل هناك طريقة للحفاظ على مسار عنوان URL الخاص بالمستندات إلى المستندات @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 &\)]

اليوم قمت بنشر بعض المواضيع في فئة المستندات، ولكن هذه المواضيع لم تظهر في صفحة المستندات. لقد قمت بإيقاف تشغيل إضافة المستندات وتشغيل السمة مرة أخرى، ولكن هذه المواضيع لا تزال غير معروضة.
شكرا لك!