Ho iniziato a usare il markdown per prendere appunti.

Uso marked per visualizzare le mie note di markdown ed è bellissimo.

Ma man mano che le mie note si allungano, trovo difficile trovare quello che voglio.

So che markdown può creare tabelle, ma è in grado di creare un sommario, che passa alle sezioni o definisce sezioni di pagina in markdown?

In alternativa, ci sono lettori / editor di markdown che potrebbero fare queste cose. La ricerca sarebbe anche una buona caratteristica.

In breve, voglio renderlo il mio fantastico strumento per prendere appunti e funzioni come scrivere un libro, ecc.

MultiMarkdown Composer sembra generare un sommario per assistere durante la modifica.

Potrebbe esserci anche l'una o l'altra libreria, che può generare TOC: vedere l' estensione TOC di Python Markdown .

Puoi provarlo.

# Table of Contents
1. [Example](#example)
2. [Example2](#example2)
3. [Third Example](#third-example)
4. [Fourth Example](#fourth-examplehttpwwwfourthexamplecom)


## Example
## Example2
## Third Example
## [Fourth Example](http://www.fourthexample.com) 

Ecco un metodo utile. Dovrebbe produrre riferimenti cliccabili in qualsiasi editor MarkDown.

# Table of contents
1. [Introduction](#introduction)
2. [Some paragraph](#paragraph1)
    1. [Sub paragraph](#subparagraph1)
3. [Another paragraph](#paragraph2)

## This is the introduction <a name="introduction"></a>
Some introduction text, formatted in heading 2 style

## Some paragraph <a name="paragraph1"></a>
The first paragraph text

### Sub paragraph <a name="subparagraph1"></a>
This is a sub paragraph, formatted in heading 3 style

## Another paragraph <a name="paragraph2"></a>
The second paragraph text

produce:

Sommario

1. introduzione
2. Alcuni paragrafi
   1. Sottosezione
3. Un altro paragrafo

Questa è l'introduzione

Alcuni testi introduttivi, formattati in stile rubrica 2

Alcuni paragrafi

Il primo paragrafo di testo

Sottosezione

Questo è un sottoparagrafo, formattato in stile titolo 3

Un altro paragrafo

Il testo del secondo paragrafo

Per gli utenti di Visual Studio Code , è consigliabile utilizzare il plug-in Markdown TOC .

Per installarlo, avvia VS Code Quick Open ( Control/⌘+ P), incolla il seguente comando e premi Invio.

ext install markdown-toc

E per generare il sommario, apri la tavolozza dei comandi ( Control/⌘+ Shift+ P) e seleziona Markdown TOC:Insert/Update optiono usa Control/⌘+ MT.

Puoi provare questo script ruby per generare il sommario da un file markdown.

 #!/usr/bin/env ruby

require 'uri'

fileName = ARGV[0]
fileName = "README.md" if !fileName

File.open(fileName, 'r') do |f|
  inside_code_snippet = false
  f.each_line do |line|
    forbidden_words = ['Table of contents', 'define', 'pragma']
    inside_code_snippet = !inside_code_snippet if line.start_with?('```')
    next if !line.start_with?("#") || forbidden_words.any? { |w| line =~ /#{w}/ } || inside_code_snippet

    title = line.gsub("#", "").strip
    href = URI::encode title.gsub(" ", "-").downcase
    puts "  " * (line.count("#")-1) + "* [#{title}](\##{href})"
  end
end

Esistono 2 modi per creare il sommario (riepilogo) nel documento markdown.

1. Manualmente

# My Table of content
- [Section 1](#id-section1)
- [Section 2](#id-section2)

<div id='id-section1'/>
## Section 1
<div id='id-section2'/>
## Section 2

2. Programmaticamente

È possibile utilizzare ad esempio uno script che genera riassunto per voi, date un'occhiata al mio progetto su GitHub - summarizeMD -

Ho provato anche altri moduli script / npm (ad esempio doctoc ) ma nessuno riproduce un sommario con ancore funzionanti.

# Table of Contents
1. [Example](#example)
2. [Example2](#example2)
3. [Third Example](#third-example)

## Example [](#){name=example}
## Example2 [](#){name=example2}
## [Third Example](#){name=third-example}

Se usi il markdown extra, non dimenticare che puoi aggiungere attributi speciali a collegamenti, intestazioni, recinzioni di codice e immagini.
https://michelf.ca/projects/php-markdown/extra/#spe-attr

I tag di ancoraggio generati da diversi parser Markdown non sono pari.

Se stai lavorando con i parser Markdown GFM (GitHub Flavored Markdown) o Redcarpet, ho scritto un plugin Vim per gestire il sommario.

Caratteristiche

1. Genera sommario per i file Markdown.

   Parser Markdown supportati:

   • GFM (GitHub Flavored Markdown)
   • Tappeto rosso

2. Aggiorna il sommario esistente.

3. Aggiorna automaticamente il sommario esistente al salvataggio.

Screenshots

uso

Genera sommario

Spostare il cursore sulla riga che si desidera aggiungere il sommario, quindi digitare un comando di seguito adatto. Il comando genererà le intestazioni dopo il cursore nell'indice.

1. :GenTocGFM

   Genera sommario in stile collegamento GFM.

   Questo comando è adatto per i file Markdown nei repository GitHub, come README.md, e per i file Markdown per GitBook.

2. :GenTocRedcarpet

   Genera sommario in stile collegamento Redcarpet.

   Questo comando è adatto a Jekyll o in qualsiasi altro luogo utilizza Redcarpet come suo parser Markdown.

   È possibile visualizzare qui per conoscere le differenze tra i collegamenti toc in stile GFM e Redcarpet.

Aggiorna manualmente il sommario esistente

Generalmente non è necessario eseguire questa operazione, il sommario esistente si aggiornerà automaticamente al salvataggio per impostazione predefinita. Se vuoi farlo manualmente, basta usare il :UpdateToccomando.

Download e documenti

https://github.com/mzlogin/vim-markdown-toc

Puoi anche usare pandocil "coltellino svizzero" per convertire "un formato markup in un altro" . Può generare automaticamente una tabella di contenuti nel documento di output se si fornisce l' --tocargomento.

Suggerimento: se si desidera un sommario htmlnell'output, è necessario fornire anche -sun documento autonomo da generare.

Riga di comando della shell di esempio:

./pandoc -s --toc input.md -o output.html

A beneficio di quelli di noi che creano README.mdfile in Atom (come ho trovato questo thread):

apm install markdown-toc

https://atom.io/packages/markdown-toc

Se vuoi usare uno strumento javascript / node.js, dai un'occhiata a markdown-toc .

Puoi generarlo usando questo bash one-liner. Presuppone che venga chiamato il file markdown FILE.md.

echo "## Contents" ; echo ; 
cat FILE.md | grep '^## ' | grep -v Contents | sed 's/^## //' | 
  while read -r title ; do 
    link=$(echo $title | tr 'A-Z ' 'a-z-') ; 
    echo "- [$title](#$link)" ; 
    done

Ho appena codificato un'estensione per python-markdown, che utilizza il suo parser per recuperare le intestazioni e genera un sommario come elenco non ordinato in formato Markdown con collegamenti locali. Il file è

• md_toc.py (era md_toc.py )

... e dovrebbe essere collocato nella markdown/extensions/directory nell'installazione markdown. Quindi, tutto ciò che devi fare è digitare i <a>tag anchor con un id="..."attributo come riferimento, quindi per un testo di input come questo:

$ cat test.md 
Hello
=====

## <a id="sect one"></a>SECTION ONE ##

something here

### <a id='sect two'>eh</a>SECTION TWO ###

something else

#### SECTION THREE

nothing here

### <a id="four"></a>SECTION FOUR

also...

... l'estensione può essere chiamata in questo modo:

$ python -m markdown -x md_toc test.md 
* Hello
    * [SECTION ONE](#sect one)
        * [SECTION TWO](#sect two)
            * SECTION THREE
        * [SECTION FOUR](#four)

... e quindi puoi incollare indietro questo toc nel tuo documento markdown (o avere un collegamento nel tuo editor di testo, che chiama lo script sul documento attualmente aperto e quindi inserisce il sommario risultante nello stesso documento).

Si noti che le versioni precedenti di python-markdownnon hanno un __main__.pymodulo e, come tale, la chiamata da riga di comando come sopra non funzionerà per quelle versioni.

Come menzionato in altre risposte, esistono diversi modi per generare automaticamente un sommario. La maggior parte sono software open source e possono essere adattati alle tue esigenze.

Ciò che mi mancava è, tuttavia, una formattazione visivamente attraente per un sommario, utilizzando le opzioni limitate fornite da Markdown. Abbiamo pensato a quanto segue:

Codice

## Content

**[1. Markdown](#heading--1)**

  * [1.1. Markdown formatting cheatsheet](#heading--1-1)
  * [1.2. Markdown formatting details](#heading--1-2)

**[2. BBCode formatting](#heading--2)**

  * [2.1. Basic text formatting](#heading--2-1)

      * [2.1.1. Not so basic text formatting](#heading--2-1-1)

  * [2.2. Lists, Images, Code](#heading--2-2)
  * [2.3. Special features](#heading--2-3)

----

All'interno del documento, si posizionerebbero i marcatori di sottoparte target in questo modo:

<div id="heading--1-1"/>
### 1.1. Markdown formatting cheatsheet

A seconda di dove e come usi Markdown, dovrebbe funzionare anche quanto segue e fornisce un codice Markdown più bello:

### 1.1. Markdown formatting cheatsheet <a name="heading--1-1"/>

Esempio di rendering

Soddisfare

1. Markdown

• 1.1. Cheatsheet di formattazione markdown
• 1.2. Dettagli sulla formattazione del markdown

2. Formattazione BBCode

• 2.1. Formattazione di base del testo

  • 2.1.1. Formattazione del testo non così semplice

• 2.2. Elenchi, immagini, codice

• 2.3. Caratteristiche speciali

---

vantaggi

• Puoi aggiungere tutti i livelli di capitoli e sottocapitoli di cui hai bisogno. Nel Sommario, questi apparirebbero come elenchi non ordinati nidificati a livelli più profondi.

• Nessun uso degli elenchi ordinati. Ciò creerebbe un rientro, non collegherebbe il numero e non può essere utilizzato per creare una numerazione decimale della classificazione come "1.1".

• Nessun uso di elenchi per il primo livello. Qui, è possibile utilizzare un elenco non ordinato, ma non necessario: il rientro e il punto elenco aggiungono solo disordine visivo e nessuna funzione qui, quindi non utilizziamo affatto un elenco per il primo livello ToC.

• Enfasi visiva sulle sezioni di primo livello nella tabella dei contenuti in grassetto.

• Indicatori di sottoparte brevi e significativi che sembrano "belli" nella barra degli URL del browser, come #heading--1-1piuttosto che marcatori contenenti parti trasformate dell'intestazione effettiva.

• Il codice utilizza le intestazioni H2 ( ## …) per le sezioni, le intestazioni H3 ( ### …) per le sottotitoli ecc. Ciò semplifica la lettura del codice sorgente perché ## …fornisce un indizio visivo più forte durante lo scorrimento rispetto al caso in cui le sezioni inizierebbero con le intestazioni H1 ( # …). È ancora logicamente coerente quando si utilizza l'intestazione H1 per il titolo del documento stesso.

• Infine, aggiungiamo una bella regola orizzontale per separare il sommario dal contenuto reale.

Per ulteriori informazioni su questa tecnica e su come la utilizziamo all'interno del software del forum Discorso , vedere qui .

Ho scritto uno script Python che analizza un file di markdown e genera un indice come elenco di markdown: md-to-toc

A differenza di altri script che ho trovato, md-to-toc supporta correttamente i titoli duplicati. Inoltre non richiede una connessione Internet, quindi funziona su qualsiasi file md, non solo su quelli disponibili da un repository pubblico.

In Visual Studio Code (VSCode) è possibile utilizzare l'estensione Markdown All in One .

Una volta installato, attenersi alla seguente procedura:

1. Premi CTRL+ SHIFT+P
2. Seleziona Markdown: Crea sommario

Ho appena iniziato a fare la stessa cosa (prendi appunti in Markdown). Uso Sublime Text 2 con il plug-in MarkdownPreview . Il parser di markdown integrato supporta [TOC].

Typora genera Tabella dei contenuti con l'aggiunta [TOC]al documento.

Su Gitlab, il markdown supporta questo: [[_TOC_]]

Usa il tuo editor di testo con un plugin.

Il tuo editor ha probabilmente un pacchetto / plugin per gestirlo. Ad esempio, in Emacs , è possibile installare il generatore TOC markdown-toc . Quindi mentre modifichi, chiama più volte M-x markdown-toc-generate-or-refresh-toc. Vale la pena associare una chiave se vuoi farlo spesso. È bravo a generare un TOC semplice senza inquinare il tuo documento con ancore HTML.

Altri editor hanno plugin simili, quindi l'elenco popolare è qualcosa del tipo:

• Emacs : markdown-toc
• Vim : markdown-toc
• Atom : markdown-toc
• VSCode : markdown -toc

Basato sulla risposta di albertodebortoli ha creato la funzione con ulteriori controlli e sostituzione dei segni di punteggiatura.

# @fn       def generate_table_of_contents markdown # {{{
# @brief    Generates table of contents for given markdown text
#
# @param    [String]  markdown Markdown string e.g. File.read('README.md')
#
# @return   [String]  Table of content in markdown format.
#
def generate_table_of_contents markdown
  table_of_contents = ""
  i_section = 0
  # to track markdown code sections, because e.g. ruby comments also start with #
  inside_code_section = false
  markdown.each_line do |line|
    inside_code_section = !inside_code_section if line.start_with?('```')

    forbidden_words = ['Table of contents', 'define', 'pragma']
    next if !line.start_with?('#') || inside_code_section || forbidden_words.any? { |w| line =~ /#{w}/ }

    title = line.gsub("#", "").strip
    href = title.gsub(/(^[!.?:\(\)]+|[!.?:\(\)]+$)/, '').gsub(/[!.,?:; \(\)-]+/, "-").downcase

    bullet = line.count("#") > 1 ? " *" : "#{i_section += 1}."
    table_of_contents << "  " * (line.count("#") - 1) + "#{bullet} [#{title}](\##{href})\n"
  end
  table_of_contents
end

MultiMarkdown 4.7 ha una macro {{TOC}} che inserisce un sommario.

Per me, la soluzione proposta da @Tum funziona come un fascino per un sommario con 2 livelli. Tuttavia, per il 3 ° livello non ha funzionato. Non mostrava il collegamento come per i primi 2 livelli, mostra 3.5.1. [bla bla bla](#blablabla) <br>invece il testo in chiaro .

La mia soluzione è un'aggiunta alla soluzione di @Tum (che è molto semplice) per le persone che hanno bisogno di un sommario con 3 o più livelli.

Al secondo livello, una semplice scheda farà correttamente il rientro per te. Ma non supporta 2 schede. Invece, devi usare una scheda e aggiungerne quante ne hai  bisogno per allineare correttamente il 3 ° livello.

Ecco un esempio usando 4 livelli (più alti sono i livelli, diventa terribile):

# Table of Contents
1. [Title](#title) <br>
    1.1. [sub-title](#sub_title) <br>
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1.1.1. [sub-sub-title](#sub_sub_title)
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1.1.1.1. [sub-sub-sub-title](#sub_sub_sub_title)

# Title <a name="title"></a>
Heading 1

## Sub-Title <a name="sub_title"></a>
Heading 2

### Sub-Sub-Title <a name="sub_sub_title"></a>
Heading 3

#### Sub-Sub-Sub-Title <a name="sub_sub_sub_title"></a>
Heading 4

Ciò fornisce il seguente risultato in cui ogni elemento del sommario è un collegamento alla sezione corrispondente. Nota anche <br>per aggiungere una nuova riga invece di trovarti sulla stessa riga.

Sommario

1. Titolo
   1.1. Sottotitolo
          1.1.1. Sub-sub-Titolo
                    1.1.1.1. Sub-sub-sub-Titolo

Titolo

Titolo 1

Sottotitolo

Titolo 2

Sub-sub-Titolo

Titolo 3

Titolo 4

A seconda del flusso di lavoro, potresti voler esaminare lo strapdown

Questo è un fork di quello originale ( http://strapdownjs.com ) che aggiunge la generazione della tabella dei contenuti.

C'è un file di configurazione apache sul repository (potrebbe non essere ancora aggiornato correttamente) per concludere al volo il semplice markdown, se preferisci non scrivere in file html.

Non sono sicuro, qual è la documentazione ufficiale per il markdown. Il riferimento incrociato può essere scritto solo tra parentesi [Heading]o con parentesi vuote [Heading][].

Entrambi funzionano con Pandoc . Così ho creato un rapido script bash, che sostituirà $ TOC nel file md con il suo TOC. (Avrai bisogno di envsubst, che potrebbe non far parte della tua distribuzione)

#!/bin/bash
filename=$1
__TOC__=$(grep "^##" $filename | sed -e 's/ /1. /;s/^##//;s/#/   /g;s/\. \(.*\)$/. [\1][]/')
export __TOC__
envsubst '$__TOC__' < $filename

Se ti capita di usare Eclipse puoi usare il collegamento Ctrl+ O(struttura), questo mostrerà l'equivalente del sommario e consentirà di cercare nei titoli delle sezioni (completamento automatico).

Puoi anche aprire la vista Struttura (Finestra -> Mostra vista -> Struttura) ma non ha una ricerca con completamento automatico.

Usa toc.py che è un piccolo script Python che genera un sommario per il tuo markdown.

Uso:

• Nel tuo file Markdown aggiungi <toc>dove vuoi posizionare il sommario.
• $python toc.py README.md(Usa il tuo nome file markdown invece di README.md )

Saluti!

Ho usato https://github.com/ekalinin/github-markdown-toc che fornisce un'utilità della riga di comando che genera automaticamente il sommario da un documento di markdown.

Nessun plug-in o macro o altre dipendenze. Dopo aver installato l'utilità, basta incollare l'output dell'utilità nella posizione nel documento in cui si desidera il sommario. Molto semplice da usare

$ cat README.md | ./gh-md-toc -

Se il tuo file Markdown deve essere visualizzato in un repository su bitbucket.org, dovresti aggiungerlo [TOC]nella posizione in cui desideri il tuo sommario. Verrà quindi generato automaticamente. Maggiori informazioni qui:

https://confluence.atlassian.com/bitbucket/add-a-table-of-contents-to-a-wiki-221451163.html

Esiste uno script Ruby chiamato mdtoc.rb che può generare automaticamente un sommario Markdown GFM ed è simile ma leggermente diverso da alcuni altri script pubblicati qui.

Dato un file Markdown di input come:

# Lorem Ipsum

Lorem ipsum dolor sit amet, mei alienum adipiscing te, has no possit delicata. Te nominavi suavitate sed, quis alia cum no, has an malis dictas explicari. At mel nonumes eloquentiam, eos ea dicat nullam. Sed eirmod gubergren scripserit ne, mei timeam nonumes te. Qui ut tale sonet consul, vix integre oportere an. Duis ullum at ius.

## Et cum

Et cum affert dolorem habemus. Sale malis at mel. Te pri copiosae hendrerit. Cu nec agam iracundia necessitatibus, tibique corpora adipisci qui cu. Et vix causae consetetur deterruisset, ius ea inermis quaerendum.

### His ut

His ut feugait consectetuer, id mollis nominati has, in usu insolens tractatos. Nemore viderer torquatos qui ei, corpora adipiscing ex nec. Debet vivendum ne nec, ipsum zril choro ex sed. Doming probatus euripidis vim cu, habeo apeirian et nec. Ludus pertinacia an pro, in accusam menandri reformidans nam, sed in tantas semper impedit.

### Doctus voluptua

Doctus voluptua his eu, cu ius mazim invidunt incorrupte. Ad maiorum sensibus mea. Eius posse sonet no vim, te paulo postulant salutatus ius, augue persequeris eum cu. Pro omnesque salutandi evertitur ea, an mea fugit gloriatur. Pro ne menandri intellegam, in vis clita recusabo sensibus. Usu atqui scaevola an.

## Id scripta

Id scripta alterum pri, nam audiam labitur reprehendunt at. No alia putent est. Eos diam bonorum oportere ad. Sit ad admodum constituto, vide democritum id eum. Ex singulis laboramus vis, ius no minim libris deleniti, euismod sadipscing vix id.

Genera questo indice:

$ mdtoc.rb FILE.md 
#### Table of contents

1. [Et cum](#et-cum)
    * [His ut](#his-ut)
    * [Doctus voluptua](#doctus-voluptua)
2. [Id scripta](#id-scripta)

Vedi anche il mio post sul blog su questo argomento.