Comment créer une sorte de table des matières dans le wiki GitHub?

Si vous regardez ici: http://en.wikipedia.org/wiki/Stack_Overflow

Vous remarquerez qu'il y a une petite section "Contenu", si vous cliquez sur l'un des liens, cela vous mènera à une section spécifique de la page.

Comment faire cela dans le wiki GitHub? Avec Markdown ou quoi qu'ils utilisent?

C'est bien démontré dans la table des matières de la feuille de triche Markdown .

##### Table of Contents  
[Headers](#headers)  
[Emphasis](#emphasis)  
...snip...    
<a name="headers"/>
## Headers

Si vous survolez un en-tête dans un fichier GitHub Markdown, vous verrez un petit lien simple à gauche de celui-ci, vous pouvez également utiliser ce lien. Le format de ce lien est <project URL#<header name>. Le <header name>doit être tout en minuscules.

Une solution possible (semi-automatisée) est celle d'Eugene Kalinin github-markdown-toc. Cet outil README.mdanalyse essentiellement votre fichier et extrait les en #-têtes de votre fichier pour créer une table des matières.

1. Téléchargez le script https://github.com/ekalinin/github-markdown-toc

2. Nourrissez-vous README.mddu script (comme indiqué dans Eugene README.md)

   cat README.md | bash github-markdown-toc

3. Coupez et collez la table des matières générée et placez-la en haut de votre README.mdfichier

Notez que cette bashimplémentation ne fonctionne que sous Linux (d'après ce que je peux dire).

En remarque, il existe une implémentation golang et il est probablement plus compliqué de se mettre au travail.

Puisque github ne peut pas utiliser TOCdirectement, mais nous avons d'autres alternatives.

Vous pouvez générer automatiquement une table des matières via l' outil en ligne:

Générer une table des matières de la table des matières à partir de GitHub Markdown ou Wiki Online

ou via l'outil local:

github-markdown-toc

https://github.com/jonschlinkert/markdown-toc

• git clone your-repo.wiki.git(ajoutez le .wikidroit avant .gitpour cloner le wiki
• npm i -g markdown-toc
• Insérer <!-- toc -->(sensible à la casse) dans le démarque de votre wiki
• markdown-toc -i my-wiki-markdown.md( -ile modifiera sur place)
• Profit

Mise à jour: je pense que https://github.com/thlorenz/doctoc est peut-être plus populaire maintenant.

Actuellement, il n'est pas possible de le faire en utilisant la syntaxe markdown ( .md). Il y a une discussion non officielle en cours sur la génération automatique de table des matières TOC sur les fichiers de démarques rendus comme README.mdqui répertorie certaines des idées.

Cependant, il existe d'autres solutions de contournement telles que:

• Utilisez AsciiDocplutôt selon la suggestion de ce commentaire . Par exemple:

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

  Vérifiez l'exemple à littlebits/react-popover( README.adoc) .

• 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

Si vous n'êtes pas en mesure de vous en tenir à Markdown , vous pouvez faire comme ci-dessous:

• sur GitHub / wiki : basculez Markdown vers MediaWiki . Utilisez la __TOC__syntaxe. Voir un exemple .
• sur GitHub / repo : basculez Markdown sur AsciiDoc . Utilisez la :toc:syntaxe. Voir la démo .

Cependant, en utilisant des fichiers Markdown dans GitHub / repo , vous pouvez l'obtenir sur les pages GitHub comme dans Wikipedia

• lorsque Jekyll est activé, il génère des pages GitHub en utilisant Kramdown par défaut
• Kramdown est livré avec Table Of Content. Utilisez la {:toc}syntaxe. Voir l'explication .

Code Visual Studio

Si vous utilisez Visual Studio Code , il existe une extension facile à utiliser appelée Markdown All in One qui peut créer la table des matières pour n'importe quel fichier .md en un instant.

Ouvrez simplement la palette de commandes ( Ctrl-Shift-P) ->Markdown: Create Table of Contents

La mise à jour automatique perturbe votre table des matières modifiée?

En guise de conseil supplémentaire, vous pouvez désactiver les "mises à jour automatiques de la table des matières lors de l'enregistrement" à l'aide

  "markdown.extension.toc.updateOnSave": false,

dans vos paramètres Visual Studio (Palette de commandes -> Préférences: Ouvrir les paramètres (JSON)).

Vous pouvez choisir le mode d'édition "MediaWiki" qui générera un toc pour les en-têtes, par exemple

== First ==

== Second ==

En raison du fait que github a sa propre façon de générer des attributs id = ".." dans les en-têtes h1, h2, h3, etc ... en version html après le traitement de Markdown (par exemple, Bitbucket utilise peu de modèles différents de titre des en-têtes de id = "slug"), il est pratique de ne pas réinventer la roue et d'utiliser la bibliothèque qui a procédé à l'ingénierie inverse.

J'ai trouvé une assez bonne bibliothèque pour cette tâche appelée markdown-toc .

Pour moi, cela me semble la meilleure solution car j'ai toujours installé node sur ma machine.

Il suffit d' exécuter NPX-démarquage toc -i file.md .

Et il semble que ce soit l'un des outils les plus populaires pour cette tâche - du moins dans l'écosystème node.js.

ls
cat <<EOF >> test.md | tee 
## Table of Contents

<!-- toc -->
- old toc 1
- old toc 2
- old toc 3
<!-- tocstop -->

## abc
This is a b c.

## xyz
This is x y z.
EOF
ls
cat test.md
npx markdown-toc -i test.md
cat test.md

production: