COT automatique en github aromatisé

Est-il possible de générer une table des matières automatique à l’aide de Github Flavored Markdown ?

J’ai créé deux options pour générer un toc pour github-flavored-markdown:

L’outil de ligne de commande DocToc ( source ) requirejs node.js

Installation:

npm install -g doctoc

Usage:

doctoc . pour append une table des matières à tous les fichiers de démarques dans le répertoire actuel et dans tous les sous-répertoires.

DocToc WebApp

Si vous voulez d’abord essayer en ligne, allez sur le site doctoc , collez le lien de la page de démarquage et cela générera une table de contenu que vous pourrez insérer en haut de votre fichier de démarquage.

Wikis et ancres Github

Comme l’a souligné Matthew Flaschen dans les commentaires ci-dessous, pour ses pages wiki, GitHub n’avait auparavant pas généré les ancres dont dépend doctoc .

MISE À JOUR: Cependant, ils ont résolu ce problème .

GitHub Pages (qui est essentiellement un wrapper pour Jekyll) semble utiliser kramdown , qui implémente tout Maruku , et supporte donc une table des matières générée automatiquement via un atsortingbut toc :

 * auto-gen TOC: {:toc} 

La première ligne commence juste une liste non ordonnée et est réellement jetée.

Cela se traduit par un ensemble nested de listes non ordonnées, utilisant les en-têtes du document.

Remarque: cela devrait fonctionner pour les pages GitHub, pas pour GitHub Flavored Markdown (GFM), utilisé dans les commentaires ou les pages wiki. AFAIK une solution n’existe pas pour cela.

Ce n’est pas automatique, mais il utilise les expressions régulières Notepad ++:

Remplacer tout d’abord par le second (supprime toutes les lignes sans en-têtes)

 ^##(#?)(#?)(.*?)$(.|\r|\n)*?(?=^##|\z) -\1\2 [\3](#\3)\n 

Ensuite (convertit les en-têtes III en espaces)

 -## - 

Ensuite (convertit les en-têtes II en espaces)

 -# - 

Ensuite (supprimer les caractères inutilisés au début et à la fin du titre du lien)

 \[ *((?:(?![ .:#!\?;]*\])[^#])*)[ #:!\?;]*\] [\1] 

Ensuite (convertissez les derniers jetons en minuscules et en tirets au lieu d’espaces)

 \]([^ \r\n]*) ([^\r\n ]*) ]\L\1-\2 

Retirez les livres finales non utilisées et les tirets initiaux:

 (?:()[-:;!\?#]+$|(\]#)-) \1\2 

Supprimez les caractères inutiles dans les liens:

 (\].*?)(?:\(|\)) \1 

Et enfin, ajoutez des parenthèses autour des liens finaux:

 \](?!\()(.*?)$ \]\(\1\) 

Et voilà! Vous pouvez même mettre cela dans une macro globale si vous le répétez suffisamment de temps.

Si vous éditez des fichiers Markdown avec Vim, vous pouvez essayer ce plugin vim-markdown-toc .

L’utilisation est simple, déplacez simplement votre curseur à l’endroit où vous souhaitez append la table des matières et lancez :GenTocGFM , terminé!

Captures d’écran:

vim-markdown-toc

Caractéristiques:

  1. Générer toc pour les fichiers Markdown. (Supporter Markdown et Redcarpet GitHub Flavored)

  2. Mettre à jour le toc existant

  3. Mise à jour automatique toc lors de la sauvegarde.

Github Flavored Markdown utilise RedCarpet comme moteur de Markdown. Du repo RedCarpet :

: with_toc_data – ajoute des ancres HTML à chaque en-tête du code HTML de sortie, pour permettre la liaison avec chaque section.

Il semble que vous ayez besoin de passer au niveau du moteur de rendu pour définir cet indicateur, ce qui n’est évidemment pas possible sur Github. Cependant, la dernière mise à jour de Github Pages, il semble que l’ancrage automatique soit activé pour les en-têtes, créant ainsi des en-têtes pouvant être liés. Pas exactement ce que vous voulez, mais cela pourrait vous aider à créer une table des matières pour votre doc un peu plus facilement (bien que manuellement).

Ce n’est pas possible, sauf pour les solutions proposées.

J’ai proposé l’ extension TOC Kramdown et d’autres possibilités à support@github.com et Steven! Ragnarök a répondu avec l’habituel:

Merci pour la suggestion et les liens. Je vais l’append à notre liste de demandes de fonctionnalités internes pour l’équipe.

Levons cette question jusqu’à ce qu’elle se produise.

Une autre solution (généralement inacceptable) consiste à utiliser asciidoc au lieu de Markdown, ce qui rend les tables des matières .

Générateur Readme Grunt

Je viens d’écrire un outil pour cela. Principalement pour mes projets github. Ceci est un plugin Grunt pour générer un fichier readme à partir de plusieurs petites sections de fichiers de démarques, avec la table des matières. Possède de nombreuses fonctionnalités et personnalisation.

Cité à partir de son readme:

Disons que vous avez une structure de readme telle que:

 - Installation - Usage -- Example -- Example Output - Documentation -- Options --- option1 --- option2 -- API - License - Consortingbuting 
  • Vous pouvez écrire une tâche pour générer Options.md partir d’ option1.md et d’ option2.md
  • Ensuite, une tâche pour générer Documentation.md partir de Options.md et API.md
  • Une autre tâche pour générer Usage.md partir des Example.md et Example Output.md
  • Et enveloppez-le en créant le Readme.md partir d’ Installation.md , Usage.md , Documentation.md , License.md et Consortingbuting.md
  • voilà!

Points forts

  • Génération automatique de table des matières
  • Génération automatique de liens Back To Top
  • Très personnalisable pour de nombreuses parties de l’image
  • Génération automatique de titres et de descriptions en haut
  • Option pour générer une image d’état de build travis en haut pour la twig désirée
  • Conçu spécialement pour les projets GitHub et GFM
  • Bannières facultatives sur le dessus pour mettre un logo ou un art ascii!

Ce plugin nécessite Grunt ~0.4.1

….

J’espère que ça aide. Le repo est situé à GitHub . Vous pouvez trouver plus d’informations sur l’installation et la liste complète des options avec des exemples.

Il est possible de générer une page Web automatiquement avec http://documentup.com/ à partir du fichier README.md . Cela ne crée pas de table des matières, mais pour beaucoup, cela pourrait résoudre la raison de vouloir créer une table des matières.

Une autre alternative à Documentup est Flatdoc: http://ricostacruz.com/flatdoc/

Gitdown est un préprocesseur de Markdown pour Github.

En utilisant Gitdown, vous pouvez:

  • Générer la table des matières
  • Trouver des URL mortes et des identificateurs de fragment
  • Inclure les variables
  • Fichiers à inclure
  • Obtenir la taille du fichier
  • Générer des badges
  • Date d’impression
  • Imprimer des informations sur le référentiel lui-même

Gitdown rationalise les tâches courantes associées à la maintenance d’une page de documentation pour un référentiel GitHub.

L’utilisation est simple:

 var Gitdown = require('gitdown'); Gitdown // Gitdown flavored markdown. .read('.gitdown/README.md') // GitHub compatible markdown. .write('README.md'); 

Vous pouvez l’avoir en tant que script séparé ou l’avoir dans le cadre de la routine de script de construction (telle que Gulp ).

Utilisez coryfklein / doctoc , un fork de thlorenz / doctoc qui n’ajoute pas ” généré avec DocToc ” à chaque table des matières.

 npm install -g coryfklein/doctoc 

L’extension Markdown-TOC est un moyen très pratique d’obtenir une table des matières pour un fichier mardown lorsque vous travaillez avec Visual Studio Code.

Il peut append un toc aux fichiers de démarques existants et même garder le toc à jour lors de la sauvegarde.

entrer la description de l'image ici

Mon collègue @schmiedc et moi-même avons créé un script GreaseMonkey qui installe un nouveau bouton TOC à gauche du bouton h1 qui utilise l’excellente bibliothèque markdown-js pour append / actualiser une table des matières.

L’avantage par rapport aux solutions comme doctoc est qu’il s’intègre dans l’éditeur de wiki de GitHub et ne nécessite pas que les utilisateurs travaillent sur leur ligne de commande (et requièrent que les utilisateurs installent des outils tels que node.js ). Dans Chrome, cela fonctionne en glissant-déposant dans la page Extensions, dans Firefox, vous devrez installer l’extension GreaseMonkey.

Il fonctionnera avec un balisage simple (c.-à-d. Qu’il ne gère pas correctement les blocs de code, car il s’agit d’une extension GitHub à démarquer). Consortingbutions bienvenues

Ceci n’est pas une réponse directe à cette question car de nombreuses personnes ont fourni des solutions de rechange. Je ne pense pas que la génération d’une table des matières ait été officiellement prise en charge par Github à ce jour. Si vous souhaitez que GitHub affiche automatiquement une table des matières sur ses pages de prévisualisation GFM, veuillez participer à la discussion sur le problème de demande de fonctionnalité officielle.

Actuellement, ce n’est pas possible en utilisant la syntaxe markdown (voir la discussion en cours à GitHub ), cependant vous pouvez utiliser des outils externes tels que:

  • Générateur de table de contenu en ligne ( raychenon / play-table-of-contents )
  • arthurhammer / github-toc – extension du navigateur qui ajoute une table des matières aux repositorys GitHub

Vous pouvez également utiliser AsciiDoc (par exemple, README.adoc ), par exemple

 :toc: macro :toc-title: :toclevels: 99 # Title ## A ### A2 ## B ### B2 

comme suggéré dans ce commentaire . Vérifiez la démo ici .

Pour Texteditor Atom de Github, jetez un œil à ce génial plug-in (ou “package” dans Atom-lingo), qui génère les fichiers “TOC (table des matières) des balises analysées” :

markdown-toc

Une fois installé en tant qu’Atom-package, vous pouvez utiliser le raccourci ctrl-alt-c pour insérer une table des matières basée sur votre structure markdown-doc à la position actuelle du curseur …

Captures d’écran:

entrer la description de l'image ici

Atom Keybindings

markdown-toc vous donne les raccourcis clavier par défaut suivants pour contrôler le plugin dans Atom:

  • ctrl-alt-c => créer la table des matières à la position du curseur
  • ctrl-alt-u => mettre à jour la table des matières
  • ctrl-alt-r => supprimer la table des matières

Fonctionnalités du plugin (à partir du fichier README du projet)

  • Liaison automatique via des balises d’ancrage, par exemple # A 1#a-1
  • Contrôle de profondeur [1-6] avec depthFrom:1 et depthTo:6
  • Activer ou désactiver les liens avec withLinks:1
  • Actualiser la liste lors de l’enregistrement avec updateOnSave:1
  • Utilisez la liste ordonnée (1. …, 2. …) avec la liste orderedList:0