TOC automatico in markdown al gusto di github

È possibile generare un sommario automatico utilizzando il markdown aromatizzato Github ?

Ho creato due opzioni per generare un toc per markdown al gusto di github:

DocToc Command Line Tool ( sorgente ) richiede node.js

npm install doctoc

npx doctoc . per aggiungere un sommario a tutti i file di markdown nella directory corrente e in tutte le directory secondarie.

DocToc WebApp

Se vuoi provarlo prima online, vai al sito del doctoc , incolla il link della pagina di markdown e genererà una tabella di contenuti che puoi inserire nella parte superiore del tuo file di markdown.

Github Wikis and Anchors

Come ha sottolineato Matthew Flaschen nei commenti qui sotto, per le sue pagine wiki GitHub in precedenza non ha generato le ancore da cui doctocdipende.

AGGIORNAMENTO: Tuttavia, hanno risolto questo problema .

GitHub Pages (che è fondamentalmente un wrapper per Jekyll) sembra usare kramdown , che implementa tutto Maruku , e quindi ha il supporto per un sommario generato automaticamente tramite un tocattributo:

* auto-gen TOC:
{:toc}

La prima riga avvia solo un elenco non ordinato e viene effettivamente eliminata.

Ciò si traduce in un set nidificato di elenchi non ordinati, utilizzando le intestazioni nel documento.

Nota: questo dovrebbe funzionare con GitHub Pages, non con GitHub Flavored Markdown (GFM) come usato nei commenti o nelle pagine wiki. AFAIK non esiste una soluzione per questo.

Se modifichi i file Markdown con Vim, puoi provare questo plugin vim-markdown-toc .

L'utilizzo è semplice, basta spostare il cursore nel punto in cui si desidera aggiungere il sommario ed eseguire :GenTocGFM , fatto!

Screenshots:

Caratteristiche:

1. Genera toc per i file Markdown. (Supporto GitHub Flavored Markdown e Redcarpet)

2. Aggiorna toc esistente.

3. Aggiornamento automatico toc al salvataggio.

Non è automatico, ma utilizza le espressioni regolari di Notepad ++:

Sostituisci tutto per primo con il secondo (rimuove tutte le righe senza intestazioni)

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

Quindi (converte le intestazioni III in spazi)

-##
        -

Quindi (converte le intestazioni II in spazi)

-#
    -

Quindi (rimuovi i caratteri non utilizzati all'inizio e alla fine del titolo del link)

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

Quindi (converti gli ultimi token in minuscolo e trattino anziché in spazi)

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

Rimuovere i chili finali e i trattini iniziali non utilizzati:

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

Rimuovi caratteri inutili nei link:

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

E infine aggiungi la parentesi attorno ai link finali:

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

E voilà! Puoi anche inserirlo in una macro globale se lo ripeti abbastanza tempo.

Non è possibile, ad eccezione delle soluzioni alternative proposte.

Ho proposto l' estensione TOC di Kramdown e altre possibilità a support@github.com e Steven! Ragnarök rispose con il solito:

Grazie per il suggerimento e i collegamenti. Lo aggiungerò al nostro elenco di richieste di funzionalità interne affinché il team possa vederlo.

Votiamo questa domanda fino a quando non accade.

Un'altra soluzione alternativa è utilizzare Asciidoc invece di Markdown, che rende i TOC . Oggi sono passato a questo approccio per i miei contenuti.

Github Flavored Markdown utilizza RedCarpet come motore Markdown. Dal repository RedCarpet :

: with_toc_data: consente di aggiungere ancore HTML a ciascuna intestazione nell'HTML di output, per consentire il collegamento a ciascuna sezione.

Sembra che dovresti arrivare a livello di renderer per impostare questo flag, che ovviamente non è possibile su Github. Tuttavia, l' ultimo aggiornamento di Github Pages, sembra che l'ancoraggio automatico sia attivato per le intestazioni, creando intestazioni collegabili. Non esattamente quello che vuoi, ma potrebbe aiutarti a creare un sommario per il tuo documento un po 'più semplice (anche se manualmente).

Un modo molto conveniente per ottenere un sommario per un file mardown quando si lavora con Visual Studio Code è l'estensione Markdown-TOC .

Può aggiungere un toc ai file di markdown esistenti e persino mantenere il toc aggiornato durante il salvataggio.

È possibile generare automaticamente una pagina Web con http://documentup.com/ dal README.mdfile. Non sta creando un sommario, ma per molti potrebbe risolvere il motivo della volontà di creare un sommario.

Un'altra alternativa a Documentup è Flatdoc: http://ricostacruz.com/flatdoc/

Gitdown è un preprocessore markdown per Github.

Usando Gitdown puoi:

• Genera sommario
• Trova URL morti e identificatori di frammenti
• Includi variabili
• Includi file
• Ottieni le dimensioni del file
• Genera badge
• Data di stampa
• Stampa le informazioni sul repository stesso

Gitdown semplifica le attività comuni associate alla gestione di una pagina di documentazione per un repository GitHub.

Usarlo è semplice:

var Gitdown = require('gitdown');

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

Puoi averlo come uno script separato o averlo come parte della routine dello script di build (come Gulp ).

Usa coryfklein / doctoc , un fork di thlorenz / doctoc che non aggiunge " generato con DocToc " ad ogni sommario.

npm install -g coryfklein/doctoc

Io e il mio collega @schmiedc abbiamo creato uno script GreaseMonkey che installa un nuovo TOCpulsante a sinistra del h1pulsante che utilizza l'eccellente markdown-jslibreria per aggiungere / aggiornare un sommario.

Il vantaggio rispetto a soluzioni come doctoc è che si integra nell'editor wiki di GitHub e non richiede agli utenti di lavorare sulla loro riga di comando (e richiede agli utenti di installare strumenti come node.js). In Chrome, funziona trascinandolo nella pagina Estensioni, in Firefox dovrai installare l'estensione GreaseMonkey.

Funzionerà con un semplice markdown (cioè non gestisce correttamente i blocchi di codice, in quanto si tratta di un'estensione GitHub al markdown). Contributi benvenuti.

Questa non è una risposta diretta a questa domanda in quanto così tante persone hanno fornito soluzioni alternative. Non credo che la generazione di un sommario sia stata ufficialmente supportata da Github fino ad oggi. Se desideri che GitHub esegua il rendering automatico di un sommario nelle pagine di anteprima di GFM, partecipa alla discussione sul problema ufficiale di richiesta di funzionalità .

Attualmente non è possibile utilizzare la sintassi di markdown (vedere la discussione in corso su GitHub ), tuttavia è possibile utilizzare alcuni strumenti esterni come:

• Generatore di indici di contenuti online ( raychenon / play-table-indice )
• arthurhammer / github-toc - estensione del browser che aggiunge un sommario ai repository GitHub

In alternativa, utilizzare AsciiDocinvece (ad es. README.adoc), Ad es

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

## A

### A2

## B

### B2

come suggerito in questo commento . Controlla la demo qui .

Per Atom di Textithitor di Github dai un'occhiata a questo fantastico plugin (o "pacchetto" in Atom-lingo), che genera file "TOC (indice) dei titoli dai markdown analizzati" :

Markdown-toc

Una volta installato come pacchetto Atom è possibile utilizzare il collegamento ctrl-alt-cper inserire un sommario basato sulla struttura del documento markdown nella posizione corrente del cursore ...

Screenshots:

Atom Keybindings

markdown-toc fornisce i seguenti tasti di scelta rapida predefiniti per controllare il plugin in Atom:

• ctrl-alt-c => crea sommario nella posizione del cursore
• ctrl-alt-u => aggiorna TOC
• ctrl-alt-r => elimina TOC

Funzionalità del plug-in (dal README del progetto)

• Collegamento automatico tramite tag di ancoraggio, ad es # A 1 →#a-1
• Controllo della profondità [1-6] con depthFrom:1 edepthTo:6
• Abilita o disabilita i collegamenti con withLinks:1
• Aggiorna elenco su Salva con updateOnSave:1
• Utilizzare l'elenco ordinato (1. ..., 2. ...) con orderedList:0

Ecco uno script di shell che ho messo insieme oggi per questo. Potrebbe essere necessario modificarlo per le tue esigenze, ma dovrebbe essere un buon punto di partenza.

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/^#//'

Se qualcuno conosce un modo migliore per eseguire tali # sostituzioni finali, si prega di aggiungere un commento. Ho provato varie cose e non ne ero contento, quindi l'ho costretto bruto.

Ora c'è un'azione GitHub che realizza questo:

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

1. Specificare la posizione del sommario (opzione) ad es README.md

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

2. Configura flusso di lavoro ad es .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 maggior parte delle altre risposte richiede l'installazione di alcuni strumenti. Ho trovato una soluzione online semplice e veloce https://imthenachoman.github.io/nGitHubTOC .

Per ogni input di markdown genera una tabella di output del contenuto. È possibile specificare il livello di intestazione minimo e massimo.

Il codice sorgente si trova su https://github.com/imthenachoman/nGitHubTOC