Come creo una sorta di tabella dei contenuti nel wiki di GitHub?

Se guardi qui: http://en.wikipedia.org/wiki/Stack_Overflow

Noterai che c'è una piccola sezione "Contenuto", se fai clic su uno dei link, verrai indirizzato a una sezione specifica della pagina.

Come posso farlo nel wiki di GitHub? Con Markdown o qualunque cosa usino?

È ben dimostrato nel sommario del Markdown Cheatsheet .

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

Se passi il mouse su un'intestazione in un file Markdown di GitHub, vedrai un piccolo collegamento semplice a sinistra di esso, puoi anche usare quel collegamento. Il formato per quel collegamento è <project URL#<header name>. Il <header name>prodotto deve essere lettere minuscole.

Una possibile soluzione (semi-automatizzata) è quella di Eugene Kalinin github-markdown-toc. Questo strumento essenzialmente README.mdanalizza il tuo file ed estrae #i titoli per creare un sommario.

1. Scarica lo script https://github.com/ekalinin/github-markdown-toc

2. Feed your README.mdto the script (come notato in Eugene's README.md)

   cat README.md | bash github-markdown-toc

3. Taglia e incolla il sommario generato e posizionalo nella parte superiore del README.mdfile

Nota che questa bashimplementazione funziona solo su Linux (da quello che posso dire).

Come nota a margine, c'è un'implementazione golang ed è probabilmente più una seccatura per lavorare.

Poiché github non può essere utilizzato TOCdirettamente, ma abbiamo altre alternative.

Puoi generare automaticamente un sommario tramite lo strumento online:

Genera sommario da GitHub Markdown o Wiki Online

o tramite lo strumento locale:

github-markdown-toc

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

• git clone your-repo.wiki.git(aggiungi la .wikidestra prima .gitper clonare il wiki
• npm i -g markdown-toc
• Inserisci <!-- toc -->( distingue tra maiuscole e minuscole) nel markdown del tuo wiki
• markdown-toc -i my-wiki-markdown.md( -ilo modificherà in posizione)
• Profitto

Aggiornamento: penso che forse https://github.com/thlorenz/doctoc sia più popolare ora.

Attualmente non è possibile farlo utilizzando la sintassi markdown ( .md). È in corso una discussione non ufficiale sulla generazione automatica dell'indice TOC sui file di markdown renderizzati, come l' README.mdelenco di alcune idee.

Tuttavia ci sono alcune altre soluzioni alternative come:

• Utilizzare AsciiDocinvece come da suggerimento da questo commento . Per esempio:

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

  Controlla l'esempio in littlebits/react-popover( README.adoc) .

• In linea Table Of Content Generator ( raychenon / play-table-of-contents )

• arthurhammer / github-toc - estensione del browser che aggiunge un sommario ai repository GitHub

Se non sei nella posizione di restare con Markdown , puoi fare come di seguito:

• su GitHub / wiki : imposta Markdown su MediaWiki . Usa la __TOC__sintassi. Vedi esempio .
• su GitHub / repo : cambia Markdown in AsciiDoc . Usa la :toc:sintassi. Guarda la demo .

Tuttavia, utilizzando i file Markdown in GitHub / repo , puoi ottenerlo su pagine GitHub come in Wikipedia

• quando Jekyll è attivato, genera pagine GitHub utilizzando Kramdown per impostazione predefinita
• Kramdown viene fornito con Table Of Content. Usa la {:toc}sintassi. Vedi la spiegazione .

Codice di Visual Studio

Se ti capita di utilizzare Visual Studio Code , esiste un'estensione facile da usare chiamata Markdown All in One che può creare il sommario per qualsiasi file .md in un istante.

Basta aprire la tavolozza dei comandi ( Ctrl-Shift-P) ->Markdown: Create Table of Contents

L'aggiornamento automatico rovina il sommario modificato?

Come ulteriore suggerimento, potresti disattivare gli "aggiornamenti automatici dell'indice al salvataggio" utilizzando

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

nelle impostazioni di Visual Studio (Tavolozza dei comandi -> Preferenze: Apri impostazioni (JSON)).

Puoi scegliere la modalità Modifica "MediaWiki" che genererà un toc per le intestazioni, ad es

== First ==

== Second ==

A causa del fatto che github ha il suo modo di generare id = ".." attributi nelle intestazioni h1, h2, h3, ecc ... nella versione html dopo l'elaborazione di Markdown (ad esempio Bitbucket usa un modello leggermente diverso di intestazioni lente per id = "slug") è utile non reinventare la ruota e utilizzare la libreria che ha invertito questo processo.

Ho trovato una libreria abbastanza buona per questa attività chiamata markdown-toc .

A me sembra la soluzione migliore perché ho sempre installato node sulla mia macchina.

Basta eseguire NPX Markdown-toc -i file.md .

E sembra che sia uno degli strumenti più popolari per questo compito, almeno nell'ecosistema 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

produzione: