Discourse-Dokumentationskategorien

||||
-|-|
:discourse2: | Zusammenfassung | Discourse Doc Categories ermöglicht es, bestimmte Kategorien für Dokumentationseinträge zu reservieren, wodurch zusätzliche Funktionen für diese Kategorien aktiviert werden.
:hammer_and_wrench: | Repository-Link | https://github.com/discourse/discourse-doc-categories
:open_book: | Installationsanleitung | So installieren Sie Plugins in Discourse

:warning: Beachten Sie, dass sich dieses Plugin noch in der aktiven Entwicklung befindet und noch nicht vollständig abgeschlossen ist.

Funktionen

Das Plugin Discourse Doc Categories ermöglicht es Ihnen, strukturierte Dokumentation auf einem bestehenden Discourse-Forum zu hosten. Es funktioniert, indem bestimmte Kategorien für Dokumentationseinträge reserviert und Funktionen bereitgestellt werden, die das Auffinden spezifischer Dokumentationsthemen erleichtern.

Sie können es in Aktion in der Kategorie Documentation sehen.

Wenn eine Kategorie als Ort für Dokumentation markiert wird, werden für diese Kategorie die folgenden Funktionen aktiviert:

  • Ein festgelegtes Thema, das als Index für alle Dokumentationsthemen in der Kategorie verwendet wird
  • Eine neue Seitenleiste zur Navigation zwischen verschiedenen Themen in der Kategorie, einschließlich integrierter Filter- und Suchfunktionen
  • Neue Berichte, die Ihnen helfen, die Integrität der Index-Themen zu wahren

Darüber hinaus verarbeitet das Plugin Umleitungen für Websites, die vom eingestellten Docs-Plugin migrieren. Dokumentationslinks von diesem Plugin werden zu ihren bestehenden Themen-URLs umgeleitet, und es gibt eine Einstellung zum Umleiten Ihrer vorherigen Dokumentations-Startseite zu Ihrer Hauptdokumentationskategorie.

Konfiguration

Konfigurationseinstellungen sind unter example.discourse.com/admin/site_settings/category/doc_categories verfügbar. Hier finden Sie die folgenden Einstellungen:

  • doc categories enabled: Aktivieren Sie dies, um das Doc Categories-Plugin zu aktivieren.
  • doc categories docs legacy enabled: Aktivieren Sie dies, wenn Sie vom veralteten Docs-Plugin migriert haben.
  • doc categories homepage: Mit der vorherigen Einstellung aktiviert, wird die Landingpage des veralteten Docs-Plugins zu dieser URL umgeleitet.

Um anzugeben, welche Kategorien für Dokumentation verwendet werden sollen, weisen Sie ihnen ein Index-Thema zu. Öffnen Sie dazu die Einstellungen der Kategorie, indem Sie auf das :wrench:-Symbol auf der Kategorieseite klicken. Klicken Sie dort auf den Link „Einstellungen“ und scrollen Sie nach unten zum Abschnitt „Dokumentationsmodus“. Verwenden Sie das Feld „Index-Thema“, um das Thema anzugeben, das für den Index der Kategorie verwendet werden soll.

Index-Themen

Die Index-Themen einer Dokumentationskategorie erfüllen zwei Zwecke:

  1. Sie sind eine zentrale Liste aller Themen, die in der Kategorie enthalten sind
  2. Die mit diesem Plugin enthaltene Seitenleiste wird durch den Inhalt des Index-Themas gefüllt

Formatierung von Index-Themen

Index-Themen können jeden gewünschten Inhalt enthalten. Damit die Seitenleiste korrekt funktioniert, müssen sie eine Aufzählungsliste (oder mehrere Aufzählungslisten) von Dokumentationsthemen enthalten. Dies können einfach die Themen-URLs in einer Liste sein, in diesem Fall zeigt die Seitenleiste den vollständigen Titel für jedes Dokumentationsthema an.

Die Anzeige des vollständigen Titels in der Seitenleiste ist möglicherweise nicht praktisch, wenn Ihre Titel länger als ein paar Wörter sind. Um kürzere Titel für ein bestimmtes Thema festzulegen, fügen Sie der URL einen verkürzten Titel gefolgt von einem Doppelpunkt (:) voran. Der gesamte Text vor dem Doppelpunkt wird in der Seitenleiste angezeigt und verlinkt zur Themen-URL.

Sie können Ihr Index-Thema in Abschnitte unterteilen und mehrere Listen mit Überschriften (jeglicher Ebene) über jedem Abschnitt verwenden – diese werden dann in der Seitenleiste in diesen Abschnitten angezeigt.

Hier ist ein Beispiel für ein Index-Thema, um Ihnen den Einstieg zu erleichtern:

Sie können mit einer optionalen kurzen Beschreibung der Kategorie beginnen.

## Erster Abschnitt
* https://discourse.example.com/t/topic-title/12
* https://discourse.example.com/t/another-topic-title/34
* Kurzer Titel: https://discourse.example.com/t/topic-with-a-long-title/56
* Ein anderer Titel: https://discourse.example.com/t/another-topic-with-a-long-title/78

## Zweiter Abschnitt
* Themen-Titel: https://discourse.example.com/t/documentation-topic/98
* https://discourse.example.com/t/new-topic/76

Dieses Beispiel erzeugt eine Dokumentations-Seitenleiste, die wie folgt aussieht:

:eyes: Sehen Sie sich das Index-Thema Documentation > Site Management an, um ein Beispiel für eine Dokumentationskategorie-Index in Aktion zu sehen: https://meta.discourse.org/t/site-management-index/308032

Pflege von Index-Themen

Während die Index-Themen nicht automatisch aktualisiert werden, wenn Inhalte in der Kategorie hinzugefügt, entfernt oder bearbeitet werden, enthält das Plugin neue Berichte, die auf Inkonsistenzen innerhalb der Index-Themen hinweisen.

  • Nicht indizierte Themen:
    example.discourse.com/admin/reports/doc_categories_missing_topics
    Dieser Bericht zeigt alle Themen in den Dokumentationskategorien an, die nicht zum Index hinzugefügt wurden.

  • Überflüssige Einträge:
    example.discourse.com/admin/reports/doc_categories_extraneous_items
    Dieser Bericht zeigt Einträge an, die im Index enthalten sind, aber wahrscheinlich nicht dort hingehören. Der Bericht gibt den Grund an, warum das Thema in den Bericht aufgenommen wurde – zum Beispiel, wenn es gelöscht wurde oder sich in einer anderen Kategorie als dem Index-Thema befindet, in dem es enthalten ist.

Zusätzliche Informationen

Das Hinzufügen der Zeichenkette in:docs zu einem Suchbegriff durchsucht alle Kategorien, die für Dokumentation markiert sind (d. h. sie haben ein Index-Thema zugewiesen).

Die maximale Anzahl von Elementen im Index wird durch die Site-Einstellung Max oneboxes per post festgelegt, die standardmäßig auf 50 steht. Wenn Sie mehr als 50 Index-Elemente benötigen, erhöhen Sie die Zahl in dieser Einstellung.

38 „Gefällt mir“
New documentation plugin in development
Discourse vs Skool
Discourse Docs
How to create a sidebar similar to meta documentation sidebar?
Using Discourse as Learning Platform
Sub-sections on the sidebar without sub-categories
I am very interested in the 'documentation' feature
Using Discourse as an enterprise wiki library
How to arrange sub categories as list items under a category
Sub-sections on the sidebar without sub-categories
Custom topic ordering
Collections
Bulk Export of Raw Post Sources with Markup
Bulk Export of Raw Post Sources with Markup
Discourse Doc Categories is now available on Business
Discourse Docs
Discourse as an LMS / Discourse integration with an LMS
Topics (with replies) bumped on title edit
Theme customize - sidebar content
Questions about subcategories displaying in wiki sidebar
Doc pages - Schema Article
Structuring an active support community migrating from Facebook
Introducing simple mode for Discourse Doc Categories
Sidebar activation issues after recent Doc Categories update
How to add this header, colored categories, and sidebar categories?
What is the best way to Publish a book with chapters?
Sidebar spacing change?
Is there a plugin that allows you to organize all the URLs of a category into one topic?
Use more often placeholder forms in documentation topics?
Published Pages for documentation?
Need Help on Category on left sidebar
Displaying "full topic" text on category page + access to subcategory from menu bar
Custom Platform
Click a category to open a subcategory page
Discourse Doc Categories links not rendering
A better way to manage indices for Doc Categories?
A better way to manage indices for Doc Categories?
Create index topic

Das ist ziemlich nett.. Ich habe mir gerade andere selbst gehostete Dokumentationslösungen angesehen (die Forenstruktur kann für neue Leser manchmal etwas verwirrend sein).

Viel Erfolg für Discourse (gegen Gitbook & andere :smiley:)

6 „Gefällt mir“

Ich würde vermuten, dass die Komponente discourse-doc-sidebar (habe ich den Namen richtig in Erinnerung?) nicht mehr benötigt wird?

3 „Gefällt mir“

Ja – die Komponente, die ursprünglich für die neue Dokumentationsseitenleiste entwickelt wurde, wurde in dieses Plugin verschoben.

4 „Gefällt mir“

Ich glaube, das funktioniert nicht mehr mit Tags? :slight_smile:

4 „Gefällt mir“

Ich liebe den Ansatz, da er sich nahtlos in die Kern-Diskurs-Navigation integriert, anstatt eine völlig neue wie im Docs-Plugin zu erstellen.
Wir werden gerne wechseln!

2 „Gefällt mir“

Ich lasse das hier einfach mal fallen, ganz sicher keine native Feature-Anfrage. Auch wenn diese vielleicht nicht speziell für dieses Plugin gelten, denke ich, dass es ausgezeichnete Funktionen für jede Dokumentationsumgebung sind - als Vorteil könnten sie auch großartige Kernergänzungen sein. :thinking:

5 „Gefällt mir“

Etwas wie die Fußnotenfunktion, aber global durch Schlüsselwörter ausgelöst, wäre für eine solche Funktion episch.

3 „Gefällt mir“

Wenn wir Hover-Vorschauen haben, die bei jedem internen Link in Ihrem Forum angezeigt werden, benötigen Sie dies nicht einmal. Die Wort-/Link-Ersetzung kann dies übernehmen, und man muss nur mit der Maus über dieses Wort fahren und den vollständigen Beitrag lesen, ohne ihn zu öffnen :smiley:

Funktionen wie diese sind sehr praktisch (da niemand gerne Dokumentationen liest, oder?) und mit der Veröffentlichung dieses Plugins, mitten auf meiner Reise, die beste Lösung für das Hosten meiner Dokumentationen zu finden, macht es mir das Ganze viel schwerer :stuck_out_tongue: Ich habe erwogen, meine Dokumentationen mit Quartz zu verschieben, wobei die Inhalte in Obsidian verwaltet werden.

2 „Gefällt mir“

Gibt es eine Chance, dass es mit 3.3 Stable kompatibel sein wird?

3 „Gefällt mir“

Ja, das ist vollständig kompatibel mit Discourse 3.3 :slight_smile:

2 „Gefällt mir“

Nein, das ist nicht der Fall:

/var/www/discourse/plugins/discourse-doc-categories/lib/doc_categories/initializers/invalidate_cache_on_enabled_setting_change.rb:8:in `apply': undefined method `on_enabled_change' for an instance of Plugin::Instance (NoMethodError)

** INKOMPATIBLES PLUGIN **
Sie können Discourse aufgrund von Fehlern im Plugin unter
/var/www/discourse/plugins/discourse-doc-categories
nicht starten.

Siehe DEV: Add plugin API to perform actions when the plugin is turned on/o… · discourse/discourse@366dfec · GitHub

4 „Gefällt mir“

Emoji-Rendering in den Titeln und Elementen der Seitenleiste wäre großartig!

3 „Gefällt mir“

Hallo Leute!

Entschuldigung, das war mein Fehler.

Ich habe einen Fehler gemacht, als Hugh mich fragte, ob das Plugin kompatibel sei, und angenommen, dass die neuen APIs, die ich bei der Entwicklung eingeführt habe, es für 3.3 stabil geschafft haben.

Leider war dies nicht wirklich der Fall und die erste stabile Version, mit der das Plugin kompatibel sein wird, ist 3.4.

Entschuldigung nochmals für die Verwirrung.

6 „Gefällt mir“

Wie wäre es mit Gruppentag und Tags?

3 „Gefällt mir“

Danke für die Klarstellung, @saquetim!

Ich bin mir nicht sicher, was Sie hier meinen – könnten Sie das bitte etwas genauer erläutern?

Docs Plugin, wir können Tags nach Gruppe in der Seitenleiste anzeigen, um zu filtern. Können wir mit dem neuen Plugin dasselbe tun?

2 „Gefällt mir“

Das neue Plugin kann das derzeit nicht. Es ist vielleicht etwas, das wir in Zukunft untersuchen werden, aber im Moment fügen wir es ihm nicht hinzu.

2 „Gefällt mir“

Ja, ja
vielen Dank!

1 „Gefällt mir“

Ich muss wirklich dumm sein, aber ich glaube, ich habe alles richtig gemacht. Ich habe ein Thema als Index für eine Kategorie benannt und das Docs-Plugin so eingestellt, dass es auf dieses Thema zeigt, aber ich sehe immer noch keine Seitenleiste. Gibt es vielleicht eine Schritt-für-Schritt-Demo mit Screenshots? Ich bin ratlos, wie ich eine Dokumentationskategorie einrichten kann. Danke!

1 „Gefällt mir“