web-dev-qa-db-fra.com

COT automatique en github-marked-markdown

Est-il possible de générer une table des matières automatique en utilisant Github Flavored Markdown ?

githubmarkdown
195
Roberto Aloi

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

L'outil en ligne de commande DocToc ( source ) requiert node.js

npm install -g doctoc

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

DocToc WebApp

Si vous voulez d'abord l'essayer en ligne, allez sur le site doctoc , collez le lien de la page de démarques et cela générera un tableau de contenu que vous pouvez insérer en haut de votre fichier de démarques. </ strike>

Github Wikis et Ancres

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

UPDATE: Cependant, ils ont corrigé ce problème .

131
Thorsten Lorenz

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

* auto-gen TOC:
{:toc}

La première ligne commence simplement une liste non ordonnée et est en fait jetée.

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

Remarque: cela devrait fonctionner pour GitHub Pages, et non pour GitHub Flavored Markdown (GFM) utilisé dans les commentaires ou les pages wiki. Autant que je sache, une solution n'existe pas pour cela.

24
Ben Scott

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

Remplacer tout le premier par le second (supprime toutes les lignes sans en-tête)

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

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

-##
        -

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

-#
    -

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

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

Puis (convertir les derniers jetons en minuscules et en tirets au lieu d'espaces)

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

Supprimez les derniers livres et les derniers tirets:

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

Supprimer les caractères inutiles dans les liens:

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

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

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

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

9
Mikaël Mayer

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

L'utilisation est simple, il suffit de déplacer votre curseur à l'endroit où vous souhaitez ajouter la table des matières et d'exécuter :GenTocGFM, c'est fait!

Captures d'écran:

vim-markdown-toc

Caractéristiques:

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

  2. Mettre à jour le toc existant.

  3. Mise à jour automatique toc on save.

8
Zhuang Ma

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

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

Il semble que vous ayez besoin d'accéder au moteur de rendu pour définir cet indicateur, ce qui n'est évidemment pas possible sous Github. Cependant, dans dernière mise à jour à 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. Ce n'est pas exactement ce que vous voulez, mais cela pourrait vous aider à créer une table des matières pour votre document un peu plus facilement (bien que manuellement).

7
Kevin Suttle

Ce n'est pas possible, à l'exception des solutions de contournement proposées.

I a proposé extension du COT de Kramdown et autres possibilités à [email protected] et Steven! Ragnarök répondit avec l'habituel:

Merci pour la suggestion et les liens. Je l'ajouterai à notre liste de demandes de fonctionnalités internes afin que l'équipe puisse la consulter.

Passons à la question jusqu'à ce que cela arrive.

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

6
Ciro Santilli 新疆改造中心 六四事件 法轮功

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

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

4
Nils

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

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

 enter image description here

3
Mathias Dpunkt

Gitdown est un préprocesseur de démarquage pour Github.

En utilisant Gitdown, vous pouvez:

  • Générer la table des matières
  • Rechercher les URL et les identificateurs de fragment morts
  • Inclure les variables
  • Fichiers d'inclusion
  • 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.

Son utilisation est simple:

var Gitdown = require('gitdown');

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

Vous pouvez soit l'avoir en tant que script séparé, soit l'intégrer à la routine de script de construction (telle que Gulp ).

3
Gajus

Utilisez coryfklein/doctoc , une fourchette de thlorenz/doctoc qui n'ajoute pas "généré avecDocToc " à chaque table des matières.

npm install -g coryfklein/doctoc
2
Cory Klein

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

L'avantage par rapport aux solutions telles que doctoc est qu'il s'intègre dans l'éditeur de wiki de GitHub et qu'il n'est pas nécessaire que les utilisateurs travaillent sur leur ligne de commande (et les oblige à installer des outils tels que node.js). Dans Chrome, cela fonctionne par glisser-déposer dans la page Extensions. Sous Firefox, vous devez installer l'extension GreaseMonkey.

Cela fonctionnera avec un marquage en clair (c’est-à-dire qu’il ne gérera pas correctement les blocs de code, car il s’agit d’une extension GitHub à démarquer). Contributions bienvenues.

1
Johannes Schindelin

Actuellement, c'est impossible en utilisant la syntaxe de démarquage (voir la discussion en cours discussion sur GitHub ), mais vous pouvez utiliser des outils externes tels que:

Vous pouvez également utiliser AsciiDoc à la place (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 .

0
kenorb

Pour Github's Texteditor Atom consultez ce plugin génial (ou "package" dans Atom-lingo), qui génère "table des matières (sommaire) à partir de balises analysées" : 

markdown-toc

Une fois installé en tant que paquet Atom, 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:

 enter image description here

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 

Plugin Features (à partir du fichier README du projet)

  • Liaison automatique via des balises d'ancrage, par ex. # A 1 → #a-1
  • Contrôle de la 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
  • Utiliser la liste ordonnée (1. ..., 2. ...) avec orderedList:0
0
Mayinx

Voici un script Shell que j’ai rassemblé aujourd’hui pour cela. Vous aurez peut-être besoin de le modifier pour répondre à vos besoins, mais cela devrait être un bon point de départ.

cat README.md \
    | sed -e '/```/ r pf' -e '/```/,/```/d' \
    | grep "^#" \
    | tail -n +2 \
    | tr -d '`' \
    | sed 's/# \([a-zA-Z0-9`. -]\+\)/- [\1](#\L\1)/' \
    | awk -F'(' '{for(i=2;i<=NF;i++)if(i==2)gsub(" ","-",$i);}1' OFS='(' \
    | sed 's/^####/      /' \
    | sed 's/^###/    /' \
    | sed 's/^##/  /' \
    | sed 's/^#//'

Si quelqu'un connaît une meilleure façon de faire ces # remplacements finaux, veuillez ajouter un commentaire. J'ai essayé diverses choses et je n'étais satisfait d'aucune de ces choses, alors je me suis contenté de le forcer.

0
John Eikenberry

Ceci n’est pas une réponse directe à cette question car de nombreuses personnes ont fourni des solutions de contournement. Je ne pense pas que la génération d'un COT 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 d'aperçu GFM, participez à la discussion sur le problème officiel demande de fonctionnalité . 

0
Xiaodong Qi