|||
-|-|-|
| Résumé | Discourse Doc Categories permet de mettre de côté certaines catégories pour la documentation, leur offrant des fonctionnalités supplémentaires.
| Lien du dépôt | https://github.com/discourse/discourse-doc-categories
| Guide d’installation | Comment installer des plugins dans Discourse
Notez que ce plugin est en cours de développement actif et n’est pas encore entièrement terminé.
Fonctionnalités
Le plugin Discourse Doc Categories vous permet d’héberger de la documentation structurée sur un forum Discourse existant. Il fonctionne en réservant des catégories spécifiques pour la documentation et en fournissant des fonctionnalités pour faciliter la recherche de sujets de documentation spécifiques.
Vous pouvez le voir en action dans la catégorie Documentation.
Lorsque vous marquez une catégorie comme emplacement de documentation, les fonctionnalités suivantes sont activées pour cette catégorie :
- Un sujet spécifié à utiliser comme index pour tous les sujets de documentation de la catégorie
- Une nouvelle barre latérale pour naviguer entre les différents sujets de la catégorie, y compris des fonctions de filtrage et de recherche intégrées
- De nouveaux rapports pour vous aider à maintenir l’intégrité des sujets d’index
De plus, le plugin gère les redirections pour les sites qui migrent depuis le plugin Docs retiré. Les liens de documentation de ce plugin redirigeront vers leurs URL de sujet existantes, et un réglage permet de rediriger votre ancienne page d’accueil de documentation vers votre catégorie de documentation principale.
Configuration
Les paramètres de configuration sont disponibles à l’adresse example.discourse.com/admin/site_settings/category/doc_categories. Vous y trouverez les paramètres suivants :
doc categories enabled: Sélectionnez pour activer le plugin Doc Categories.doc categories docs legacy enabled: Sélectionnez ceci si vous avez migré depuis le plugin Docs obsolète.doc categories homepage: Avec le paramètre précédent activé, la page d’accueil du plugin Docs obsolète redirigera vers cette URL.
Pour spécifier quelles catégories seront utilisées pour la documentation, assignez-leur un sujet d’index. Pour ce faire, ouvrez les paramètres de la catégorie en cliquant sur l’icône 
sur la page de la catégorie. De là, cliquez sur le lien “Paramètres” et faites défiler jusqu’à la section “Mode documentation”. Utilisez le champ “Sujet d’index” pour spécifier le sujet qui sera utilisé pour l’index de la catégorie.
Sujets d’index
Les sujets d’index d’une catégorie de documentation servent deux objectifs :
- Ils constituent une liste centrale de tous les sujets inclus dans la catégorie.
- La barre latérale incluse avec ce plugin est peuplée par le contenu du sujet d’index.
Formatage des sujets d’index
Les sujets d’index peuvent inclure le contenu de votre choix. Pour que la barre latérale fonctionne correctement, ils doivent inclure une liste à puces (ou plusieurs listes à puces) de sujets de documentation. Il peut simplement s’agir des URL des sujets dans une liste, auquel cas la barre latérale affichera le titre complet de chaque sujet de documentation.
Avoir le titre complet dans la barre latérale peut ne pas être pratique si vos titres sont plus longs que quelques mots. Pour définir des titres plus courts pour un sujet particulier, précédez l’URL d’un titre abrégé suivi d’un deux-points (:). Tout le texte avant les deux-points sera affiché dans la barre latérale et il pointera vers l’URL du sujet.
Vous pouvez diviser votre sujet d’index en sections et utiliser plusieurs listes avec des titres (de n’importe quel niveau) au-dessus de chacune d’elles - elles seront alors affichées dans la barre latérale dans ces sections.
Voici un exemple de sujet d’index pour vous aider à démarrer :
Vous pouvez commencer par une description facultative et brève de la catégorie.
## Première section
* https://discourse.example.com/t/topic-title/12
* https://discourse.example.com/t/another-topic-title/34
* Titre court : https://discourse.example.com/t/topic-with-a-long-title/56
* Autre titre : https://discourse.example.com/t/another-topic-with-a-long-title/78
## Deuxième section
* Titre du sujet : https://discourse.example.com/t/documentation-topic/98
* https://discourse.example.com/t/new-topic/76
Cet exemple produira une barre latérale de documentation qui ressemble à ceci :
Voir l’index Documentation > Site Management pour un exemple de fonctionnement d’un index de catégorie de documentation : https://meta.discourse.org/t/site-management-index/308032
Maintenance des sujets d’index
Bien que les sujets d’index ne soient pas mis à jour automatiquement lorsque du contenu est ajouté, supprimé ou modifié dans la catégorie, le plugin inclut de nouveaux rapports qui mettent en évidence les incohérences dans les sujets d’index.
-
Sujets non indexés :
example.discourse.com/admin/reports/doc_categories_missing_topics
Ce rapport montre tous les sujets des catégories de documentation qui n’ont pas été ajoutés à l’index. -
Éléments superflus :
example.discourse.com/admin/reports/doc_categories_extraneous_items
Ce rapport montre les éléments inclus dans l’index qui semblent ne pas y appartenir. Le rapport indiquera la raison pour laquelle le sujet a été inclus dans le rapport - par exemple, s’il a été supprimé ou s’il se trouve dans une catégorie différente de celle dans laquelle il est inclus.
Informations supplémentaires
L’ajout de la chaîne in:docs à un terme de recherche recherchera dans toutes les catégories marquées pour la documentation (c’est-à-dire qu’elles ont un sujet d’index assigné).
Le nombre maximum d’éléments dans l’index est défini par le paramètre du site Max oneboxes per post, qui est de 50 par défaut. Si vous avez besoin de plus de 50 éléments d’index, augmentez le nombre dans ce paramètre.
)
J’explorais la possibilité de déplacer ma documentation vers 
