||||
-|-|
| Résumé | Discourse Doc Categories permet de réserver certaines catégories à la documentation, ce qui active des fonctionnalités supplémentaires pour celles-ci.
| 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 développement actif et n’est pas encore entièrement terminé.
Fonctionnalités
Le plugin Discourse Doc Categories vous permet d’héberger une documentation structurée sur un forum Discourse existant. Il fonctionne en réservant des catégories spécifiques à 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.
Lorsqu’une catégorie est marquée comme emplacement pour la 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, incluant des fonctions de filtrage et de recherche intégrées
- De nouveaux rapports pour vous aider à maintenir l’intégrité des sujets indexés
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 il existe un paramètre pour 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: Cochez pour activer le plugin Doc Categories.doc categories docs legacy enabled: Cochez cette option si vous avez migré depuis le plugin Docs déprécié.doc categories homepage: Avec le paramètre précédent activé, la page d’accueil du plugin Docs déprécié redirigera vers cette URL.
Pour spécifier quelles catégories seront utilisées pour la documentation, assignez-leur un sujet 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 ‘Settings’ et faites défiler jusqu’à la section ‘Documentation mode’. Utilisez le champ ‘Index topic’ pour spécifier le sujet qui sera utilisé pour l’index de la catégorie.
Sujets index
Les sujets index d’une catégorie de documentation servent à deux fins :
- 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 index
Formatage des sujets index
Les sujets index peuvent inclure n’importe quel 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 s’agir simplement 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, donc 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 le deux-points sera affiché dans la barre latérale et il renverra vers l’URL du sujet.
Vous pouvez diviser votre sujet 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 index pour vous aider à démarrer :
Vous pouvez commencer par une brève description optionnelle 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 ressemblera à ceci :
Voir le sujet index Documentation > Site Management pour un exemple d’un index de catégorie de documentation en action : https://meta.discourse.org/t/site-management-index/308032
Maintenance des sujets index
Bien que les sujets index ne soient pas mis à jour automatiquement lorsque le contenu de la catégorie est ajouté, supprimé ou modifié, le plugin inclut de nouveaux rapports qui mettent en évidence les incohérences au sein des sujets 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 du sujet index dans lequel il est inclus.
Informations supplémentaires
Ajouter 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 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 par défaut à 50. 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 
