COT automatique dans la démarque aromatisée au github

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 le démarquage aromatisé au github:

L'outil de ligne de commande DocToc ( source ) nécessite node.js

npm install doctoc

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

DocToc WebApp

Si vous voulez l'essayer en ligne d'abord, allez sur le site doctoc , collez le lien de la page de démarque et cela générera une table des matières que vous pourrez insérer en haut de votre fichier de démarque.

Wikis et ancres Github

Comme Matthew Flaschen l'a souligné dans les commentaires ci-dessous, pour ses pages wiki, GitHub ne générait pas auparavant les ancres qui en doctocdépendent.

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 prend donc en charge une table des matières générée automatiquement via un tocattribut:

* auto-gen TOC:
{:toc}

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

Il en résulte un ensemble imbriqué de listes non ordonnées, à l'aide des en-têtes du document.

Remarque: cela devrait fonctionner pour les pages GitHub, et non pour GitHub Flavored Markdown (GFM) comme utilisé dans les commentaires ou les pages wiki. AFAIK il n'existe pas de solution pour cela.

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 ajouter la table des matières et exécutez :GenTocGFM, c'est fait!

Captures d'écran:

Fonctionnalités:

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

2. Mettre à jour le toc existant.

3. Mise à jour automatique du toc lors de l'enregistrement.

Ce n'est pas automatique, mais il utilise des 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

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]

Ensuite (convertissez les derniers jetons en minuscules et tiret au lieu d'espaces)

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

Retirez les derniers livres et les tirets initiaux inutilisés:

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

Supprimez les caractères inutiles dans les liens:

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

Et enfin ajouter 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.

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

J'ai proposé l' extension Kramdown TOC 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'ajouter à notre liste de demandes de fonctionnalités internes pour que l'équipe puisse la voir.

Intéressons-nous à cette question jusqu'à ce qu'elle se produise.

Une autre solution consiste à utiliser Asciidoc au lieu de Markdown, qui rend les tables des matières . Je suis passé à cette approche pour mon contenu de nos jours.

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

: with_toc_data - ajoute des ancres HTML à chaque en-tête dans le code HTML de sortie, pour permettre un lien vers chaque section.

Il semble que vous deviez accéder au niveau du rendu pour définir ce drapeau, ce qui n'est évidemment pas possible sur Github. Cependant, la dernière mise à jour de Github Pages, il semble que l'ancrage automatique est activé pour les en-têtes, créant des en-têtes pouvant être liés. Pas exactement ce que vous voulez, mais cela pourrait vous aider à créer un TOC pour votre document un peu plus facilement (quoique manuellement).

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

Il peut ajouter un toc aux fichiers de démarque existants et même garder le toc à jour lors de l'enregistrement.

Il est possible de générer automatiquement une page Web avec http://documentup.com/ à partir du README.mdfichier. Il ne s'agit pas de créer une 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 démarque pour Github.

En utilisant Gitdown, vous pouvez:

• Générer une table des matières
• Rechercher des URL et des identificateurs de fragments morts
• Inclure des variables
• Inclure des fichiers
• 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'avoir dans le cadre de la routine de script de construction (comme 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

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

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

Il fonctionnera avec un markdown simple (c'est-à-dire qu'il ne gère pas correctement les blocs de code, car c'est une extension GitHub pour le markdown). Les contributions sont les bienvenues.

Ce n'est pas une réponse directe à cette question car tant de gens ont fourni des solutions de contournement. 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 leurs pages d'aperçu GFM, veuillez participer à la discussion sur le problème de demande de fonctionnalité officielle .

Actuellement, il n'est pas possible d' utiliser la syntaxe de démarquage (voir la discussion en cours sur GitHub ), mais vous pouvez utiliser certains outils externes tels que:

• En ligne Tableau de générateur de contenu ( raychenon / play-table des matières )
• arthurhammer / github-toc - extension de navigateur qui ajoute une table des matières aux dépôts GitHub

Vous pouvez également utiliser à la AsciiDocplace (par exemple README.adoc), par exemple

:toc: macro
:toc-title:
:toclevels: 99
# Title

## A

### A2

## B

### B2

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

Pour Texteditor Atom de Github, consultez ce plugin génial (ou "package" dans Atom-lingo), qui génère "TOC (table des matières) des titres à partir de fichiers d'analyse démarqués" :

markdown-toc

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

Captures d'écran:

Raccourcis clavier Atom

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

• ctrl-alt-c => créer une 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 la profondeur [1-6] avec depthFrom:1etdepthTo:6
• Activez ou désactivez les liens avec withLinks:1
• Actualiser la liste lors de l'enregistrement avec updateOnSave:1
• Utilisez la liste ordonnée (1. ..., 2. ...) avec orderedList:0

Voici un script shell que j'ai jeté ensemble aujourd'hui pour cela. Il se peut que vous deviez l'ajuster à 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 d'effectuer ces # derniers remplacements, veuillez ajouter un commentaire. J'ai essayé différentes choses et je n'étais pas satisfait de tout, alors je l'ai forcé brutalement.

Il y a maintenant une action GitHub accomplissant ceci:

https://github.com/marketplace/actions/toc-generator

1. Spécifiez l'emplacement de la table des matières (option), par exemple README.md

<!-- START doctoc -->
<!-- END doctoc -->

2. Configuration du flux de travail, par exemple .github/workflows/toc.yml

on: push
name: TOC Generator
jobs:
  generateTOC:
    name: TOC Generator
    runs-on: ubuntu-latest
    steps:
      - uses: technote-space/toc-generator@v2

La majorité des autres réponses nécessitent d'installer un outil. J'ai trouvé une solution en ligne rapide et facile https://imthenachoman.github.io/nGitHubTOC .

Pour toute entrée de démarque, il génère une table de sortie de contenu. Vous pouvez spécifier le niveau de cap minimum et maximum.

Le code source est situé sur https://github.com/imthenachoman/nGitHubTOC