 |
Résumé | DiscoTOC vous permet de générer une table des matières interactive pour vos sujets en un seul clic ! |
 |
Aperçu | Aperçu sur Discourse Theme Creator |
 |
Lien du dépôt | https://github.com/discourse/DiscoTOC |
 |
Nouveau sur les thèmes Discourse ? | Guide débutant pour utiliser les thèmes Discourse |
Installer ce composant de thème
Exemples
Bureau
Mobile
Fonctionnalités
toc = table des matières
-
Génère automatiquement toute la table des matières via un bouton dans le menu des paramètres du rédacteur
-
La table des matières sera toujours visible à l’écran - elle défile avec le contenu comme le widget de progression du sujet
-
Lorsque vous défilez au-delà des sections du sujet, l’élément actif dans la table des matières sera mis en surbrillance (en bleu)
-
Chaque entrée de la table des matières pointe vers l’ancrage du titre, vous pouvez donc également lier une section spécifique depuis un autre sujet ou message
-
Cliquer sur n’importe quel lien de la table des matières indique au navigateur de naviguer vers la section concernée (défilement fluide)
-
Dans les sujets avec des réponses, un bouton Sommaire / Chronologie permet aux lecteurs de basculer entre la table des matières et la chronologie normale du sujet. Le choix est mémorisé dans le navigateur
-
Fonctionne avec le plugin Discourse Docs
-
Prise en charge optionnelle des tables des matières dans les réponses, pas seulement dans le premier message
-
Prise en charge RTL
Comment ça marche ?
En résumé, il recherche les titres dans les sujets qui sont marqués pour avoir une table des matières (via le bouton du rédacteur) et si le sujet actuel est marqué, il prend tous les titres et les met dans la table des matières (imbriqués selon l’ordre des niveaux de titres) - cela signifie que votre markdown doit être syntaxiquement correct.
# titre 1
## titre 2
### titre 3
#### titre 4
##### titre 5
Vous êtes libre d’aller en avant et en arrière dans les niveaux de titres, mais l’ordre doit être correct
# titre 2
## titre 3
## titre 3
### titre 4
## titre 3
# titre 2
etc...
Quelques choses à savoir sur les titres compatibles
h1àh5sont inclus.h6ne l’est pas- Les titres à l’intérieur des citations sont ignorés, donc les citations ne pollueront pas la table des matières
- La table des matières n’apparaît que si le message a au moins autant de titres que le paramètre Titre min. de la table des matières (3 par défaut)
Comment fonctionnent les liens dans la table des matières ?
Chaque titre dans un message cuit reçoit un ancrage sous la forme p-<id du message>-<slug du titre>-<nombre> — c’est la cible derrière un titre. DiscoTOC pointe vers ces ancres plutôt que d’en inventer ses propres.
Comme ces ancres incluent la position du titre dans le message, elles changent si vous réorganisez ou renommez les titres. Si vous liez des sections depuis ailleurs, vous pouvez ajouter des ancres nommées stables au-dessus du titre :
<div><a name="ma-section"></a></div>
## Ma section
Puis liez vers /t/votre-slug-de-sujet/1234#ma-section. Discourse permet <a name="..."> dans les messages. Les propres entrées de DiscoTOC utiliseront toujours les ancres de titres principales, mais les vôtres continueront de fonctionner indépendamment des modifications.
Paramètres
| Nom | Description |
|---|---|
| niveau de confiance minimum pour créer une table des matières | Nécessaire pour voir le bouton de la table des matières dans le rédacteur |
| texte de la table des matières du rédacteur | Texte qui apparaît en haut du rédacteur pour indiquer que le sujet aura une table des matières |
| catégories de table des matières automatique | Activer automatiquement les catégories |
| tags de table des matières automatique | Activer automatiquement la table des matières sur les sujets avec ces tags |
| activer la table des matières pour les réponses | Permet la table des matières pour les réponses. Les tables des matières pour les réponses ne sont pas affectées par les paramètres tags de table des matières automatique et catégories de table des matières automatique et doivent être insérées manuellement |
| Titre min. de la table des matières | Nombre minimum de titres dans un sujet pour que la table des matières soit affichée |
texte de la table des matières du rédacteur est ce qui s’affiche dans l’aperçu du rédacteur pour indiquer qu’une table des matières sera générée :
Traductions
| Traduction | Défaut |
|---|---|
| table_of_contents | table des matières |
| insert_table_of_contents | Insérer la table des matières |
| jump_bottom | Aller à la fin |
| toggle_toc.show_timeline | Chronologie |
| toggle_toc.show_toc | Sommaire |
table_of_contents: "table des matières"
cela est utilisé pour le bouton qui ouvre la table des matières sur mobile
insert_table_of_contents: "Insérer la table des matières"
cela est utilisé comme texte pour le bouton de la table des matières dans le menu des paramètres du rédacteur
toggle_toc.show_toc: "Sommaire"
toggle_toc.show_timeline: "Chronologie"
ces étiquettes identifient le bouton qui bascule entre la table des matières et la chronologie du sujet
Comment créer une table des matières ?
- Écrivez un sujet avec des titres syntaxiquement corrects
- Cliquez sur le bouton de la table des matières dans le menu des paramètres du rédacteur. Par défaut, il n’apparaît que sur le premier message d’un sujet ; activez le paramètre activer la table des matières pour les réponses pour l’utiliser également dans les réponses
- Profitez-en.
Que se passe-t-il pour le widget de progression du sujet lorsqu’un sujet a une table des matières ?
Il n’y a pas assez d’espace pour afficher les deux en même temps, donc dans un sujet avec une table des matières, le widget de progression du sujet est masqué pendant que vous êtes sur le premier message, et vous voyez la table des matières à la place. Une fois que vous avez défilé au-delà du premier message, la table des matières est remplacée par le widget de progression du sujet normal pendant que vous lisez les réponses. (Avec activer la table des matières pour les réponses activé, une réponse qui a sa propre table des matières affiche celle-ci à la place.)
Dans les sujets avec plus d’un message, un bouton Sommaire / Chronologie permet aux lecteurs de basculer entre les deux, et la préférence est mémorisée dans leur navigateur.
Sur les écrans étroits, la table des matières s’ouvre en superposition via un bouton dans la zone de progression du sujet.
Y a-t-il des inconvénients à utiliser ce composant ?
Presque tout se passe côté client, donc vous pouvez supprimer le composant à tout moment et vos messages seront rendus comme avant. La seule chose qui touche votre contenu est le bouton du rédacteur : il enveloppe le message dans un marqueur <div data-theme-toc="true">, c’est ainsi que le composant sait que le message doit avoir une table des matières. Si vous désinstallez le composant, cet enveloppement reste dans le message mais n’a aucun effet visible.
Limitations
Les titres h6 et les titres à l’intérieur des citations ne sont pas inclus dans la table des matières.
Crédits
Cela a commencé comme un hard fork de la bibliothèque tocify.js de Greg Franko, et a depuis été réécrit comme des composants Ember natifs. Il n’y a aucune dépendance externe ni requête.
Un grand merci à @erlend_sh pour ses nombreux retours précieux et à @david pour son aide avec les traductions.