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

102

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?

Evan
la source
3
En relation, mais pas en double exact, cela entre plus en détail: stackoverflow.com/q/9721944/2291
Jon Adams

Réponses:

111

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.

RyPeck
la source
36
Il existe sûrement un moyen de le générer automatiquement comme la _ _ TOC _ _ de MediaWiki?
LB--
17
@ LB--: Si vous éditez une page wiki GitHub et changez le menu déroulant "style d'édition" en "MediaWiki", vous pouvez simplement utiliser le MediaWiki __TOC__directement. Il est clair que la logique d'autogénération sous-jacente est là. Mais la fonctionnalité ne semble pas être exposée dans leur style d'édition Markdown. C'est vraiment dommage. Commençons tous à envoyer des demandes de fonctionnalités pour cela et peut-être qu'ils l'activeront.
Andrew Janke
3
Je me rétracte sur la «logique d'autogénération sous-jacente» qui est là; il semble que les différents "styles d'édition" passent par différents moteurs de rendu. Pourtant, ce serait génial d'avoir cela dans la version MD car c'est assez populaire et ne peut pas être difficile à ajouter.
Andrew Janke
5
@AndrewJanke Je me suis penché davantage sur la question, il semble que le format MarkDown ne prend pas en charge la génération automatique de tables des matières, et ils en sont fiers.
LB--
6
Il y a un problème à créer des liens. Ils doivent être en minuscules. Je ne le savais pas et je me demandais pourquoi ma table des matières ne fonctionnait pas. J'ai utilisé à la #Headersplace de #headers. Je pensais que c'était une faute de frappe dans votre réponse. Peut-être pouvez-vous ajouter à votre réponse cette information.
t3chb0t
20

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.

John Tran
la source
14

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.

corysimmons
la source
12

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:

Kenorb
la source
1
Oui, j'ai été converti en asciidoc en grande partie pour la ToC et les liens vers les en-têtes. J'en ai marre d'attendre que Markdown rattrape son retard.
Ciro Santilli 郝海东 冠状 病 六四 事件 法轮功
8

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 .
Chetabahana
la source
5

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.

entrez la description de l'image ici

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

Original MD Après l'insertion automatique de la table des matières

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)).

np8
la source
2

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:

entrez la description de l'image ici

stopsopa
la source