Empecé a usar Markdown para tomar notas.

Utilizo marcado para ver mis notas de descuento y es hermoso.

Pero a medida que mis notas se alargan, me resulta difícil encontrar lo que quiero.

Sé que Markdown puede crear tablas, pero ¿es capaz de crear una tabla de contenido, que salte a secciones o definir secciones de página en Markdown?

Alternativamente, ¿hay lectores / editores de descuento que puedan hacer tales cosas? La búsqueda sería una buena característica para tener también.

En resumen, quiero que sea mi asombrosa herramienta para tomar notas y funciones como escribir un libro, etc.

MultiMarkdown Composer parece generar una tabla de contenido para ayudar durante la edición.

También puede haber una u otra biblioteca, que puede generar TOC: consulte Python Markdown TOC Extension .

Puedes probar esto.

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

Aquí hay un método útil. Debe producir referencias clicables en cualquier editor de 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:

Tabla de contenido

1. Introducción
2. Algun parrafo
   1. Subpárrafo
3. Otro parrafo

Esta es la introduccion

Algún texto de introducción, formateado en el estilo del encabezado 2

Algun parrafo

El primer texto del párrafo

Subpárrafo

Este es un subpárrafo, formateado en el estilo del encabezado 3

Otro parrafo

El segundo texto del párrafo

Para los usuarios de Visual Studio Code , una buena idea es usar el complemento Markdown TOC .

Para instalarlo, inicie VS Code Quick Open ( Control/⌘+ P), pegue el siguiente comando y presione Entrar.

ext install markdown-toc

Y para generar la tabla de contenido, abra la paleta de comandos ( Control/⌘+ Shift+ P) y seleccione Markdown TOC:Insert/Update optiono use Control/⌘+ MT.

Puede probar este script de ruby para generar la tabla de contenido desde un archivo de rebajas.

 #!/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

Hay 2 formas de crear su TOC (resumen) en su documento de descuento.

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. programáticamente

Se puede utilizar, por ejemplo, un script que genera resumen para usted, eche un vistazo a mi proyecto en GitHub - summarizeMD -

También probé otro módulo script / npm (por ejemplo, doctoc ) pero nadie reproduce una tabla de contenido con anclas que funcionen.

# 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}

Si usa markdown extra, no olvide que puede agregar atributos especiales a enlaces, encabezados, cercas de código e imágenes.
https://michelf.ca/projects/php-markdown/extra/#spe-attr

Las etiquetas de anclaje generadas por diferentes analizadores de Markdown no son uniformes.

Si está trabajando con analizadores Markdown GFM (GitHub Flavored Markdown) o Redcarpet, escribí un complemento Vim para manejar la tabla de contenido.

Caracteristicas

1. Generar tabla de contenido para archivos Markdown.

   Analizadores de Markdown compatibles:

   • GFM (GitHub con sabor Markdown)
   • Alfombra roja

2. Actualice la tabla de contenido existente.

3. Actualización automática de la tabla de contenido existente al guardar.

Capturas de pantalla

Uso

Generar tabla de contenido

Mueva el cursor a la línea a la que desea agregar la tabla de contenido, luego escriba un comando a continuación que le convenga. El comando generará encabezados después del cursor en la tabla de contenido.

1. :GenTocGFM

   Generar tabla de contenido en estilo de enlace GFM.

   Este comando es adecuado para archivos Markdown en repositorios de GitHub, como README.md, y archivos Markdown para GitBook.

2. :GenTocRedcarpet

   Generar tabla de contenido en estilo de enlace Redcarpet.

   Este comando es adecuado para Jekyll o en cualquier otro lugar que use Redcarpet como su analizador Markdown.

   Puede ver aquí para conocer las diferencias entre los enlaces toc de estilo GFM y Redcarpet.

Actualice la tabla de contenido existente manualmente

Generalmente no necesita hacer esto, la tabla de contenido existente se actualizará automáticamente al guardar de forma predeterminada. Si quieres hacerlo manualmente, solo usa el :UpdateToccomando.

Descargas y documentos

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

También podría usar pandocla "navaja suiza" para convertir "un formato de marcado a otro" . Puede generar automáticamente una tabla de contenido en el documento de salida si proporciona el --tocargumento.

Sugerencia: si desea una tabla de contenido en la htmlsalida, también debe proporcionar el -sque genera un documento independiente.

Ejemplo de línea de comando de shell:

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

Para el beneficio de aquellos de nosotros haciendo README.mdarchivos en Atom (cómo encontré este hilo):

apm install markdown-toc

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

Si desea utilizar una herramienta javascript / node.js, eche un vistazo a markdown-toc .

Puede generarlo usando este bash one-liner. Asume que se llama a su archivo de descuento 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

Acabo de codificar una extensión para python-markdown, que usa su analizador sintáctico para recuperar encabezados, y genera un TOC como una lista desordenada con formato Markdown con enlaces locales. El archivo es

• md_toc.py (era md_toc.py )

... y debe colocarse en el markdown/extensions/directorio en la instalación de rebajas. Luego, todo lo que tiene que hacer es escribir <a>etiquetas de anclaje con un id="..."atributo como referencia, por lo que para un texto de entrada como este:

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

... la extensión se puede llamar así:

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

... y luego puede pegar este toc en su documento de rebajas (o tener un acceso directo en su editor de texto, que llama a la secuencia de comandos en el documento abierto actualmente, y luego inserta el TOC resultante en el mismo documento).

Tenga en cuenta que las versiones anteriores de python-markdownno tienen un __main__.pymódulo y, como tal, la llamada a la línea de comandos como se indicó anteriormente no funcionará para esas versiones.

Como se menciona en otras respuestas, hay varias formas de generar una tabla de contenido automáticamente. La mayoría son software de código abierto y se pueden adaptar a sus necesidades.

Sin embargo, lo que me faltaba es un formato visualmente atractivo para una tabla de contenido, utilizando las opciones limitadas que ofrece Markdown. Se nos ocurrió lo siguiente:

Código

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

----

Dentro de su documento, colocaría los marcadores de subparte de destino de esta manera:

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

Dependiendo de dónde y cómo use Markdown, lo siguiente también debería funcionar, y proporciona un código de Markdown más atractivo:

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

Representación de ejemplo

Contenido

1. Markdown

• 1.1. Hoja de trucos de formato Markdown
• 1.2. Detalles de formato de rebajas

2. Formato BBCode

• 2.1. Formato de texto básico

  • 2.1.1 Formato de texto no tan básico

• 2.2. Listas, Imágenes, Código

• 2.3. Características especiales

---

Ventajas

• Puede agregar tantos niveles de capítulos y subcapítulos como necesite. En la Tabla de contenido, aparecerían como listas desordenadas anidadas en niveles más profundos.

• No uso de listas ordenadas. Esto crearía una sangría, no vincularía el número y no se puede usar para crear una numeración de clasificación decimal como "1.1".

• No se utilizan listas para el primer nivel. Aquí, es posible usar una lista desordenada, pero no es necesaria: la sangría y la viñeta simplemente agregan desorden visual y no funcionan aquí, por lo que no usamos una lista para el primer nivel de ToC.

• Enfoque visual en las secciones de primer nivel en la tabla de contenido en negrita.

• Marcadores de subparte cortos y significativos que se ven "hermosos" en la barra de URL del navegador, en #heading--1-1lugar de marcadores que contienen piezas transformadas del encabezado real.

• El código usa encabezados H2 ( ## …) para secciones, encabezados H3 ( ### …) para subtítulos, etc. Esto hace que el código fuente sea más fácil de leer porque ## …proporciona una pista visual más fuerte cuando se desplaza en comparación con el caso en que las secciones comenzarían con encabezados H1 ( # …) Todavía es lógicamente consistente ya que utiliza el encabezado H1 para el título del documento en sí.

• Finalmente, agregamos una buena regla horizontal para separar la tabla de contenido del contenido real.

Para obtener más información sobre esta técnica y cómo la usamos dentro del discurso del software del foro , consulte aquí .

Escribí un script de Python que analiza un archivo de descuento y genera una tabla de contenido como una lista de descuento: md-to-toc

A diferencia de otros scripts que he encontrado, md-to-toc admite correctamente títulos duplicados. Tampoco requiere una conexión a Internet, por lo que funciona en cualquier archivo md, no solo en aquellos disponibles en un repositorio público.

En Visual Studio Code (VSCode) puede usar la extensión Markdown All in One .

Una vez instalado, siga los pasos a continuación:

1. Presione CTRL+ SHIFT+P
2. Seleccione Markdown: Crear tabla de contenido

Acabo de empezar a hacer lo mismo (tomar notas en Markdown). Uso Sublime Text 2 con el complemento MarkdownPreview . El analizador de rebajas incorporado es compatible [TOC].

Typora genera Tabla de contenido al agregar [TOC]a su documento.

En Gitlab, Markdown admite esto: [[_TOC_]]

Simplemente use su editor de texto con un complemento.

Su editor posiblemente tiene un paquete / complemento para manejar esto por usted. Por ejemplo, en Emacs , puede instalar el generador de TOC markdown-toc . Luego, mientras edita, simplemente llame repetidamente M-x markdown-toc-generate-or-refresh-toc. Vale la pena un enlace clave si quieres hacerlo a menudo. Es bueno para generar un TOC simple sin contaminar su documento con anclajes HTML.

Otros editores tienen complementos similares, por lo que la lista popular es algo así como:

• Emacs : markdown-toc
• Vim : markdown-toc
• Átomo : markdown-toc
• VSCode : markdown-toc

Basado en albertodebortoli, la respuesta creó la función con verificaciones adicionales y la sustitución de signos de puntuación.

# @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 tiene una macro {{TOC}} que inserta una tabla de contenido.

Para mí, la solución propuesta por @Tum funciona de maravilla para una tabla de contenido con 2 niveles. Sin embargo, para el 3er nivel no funcionó. No mostró el enlace como para los primeros 2 niveles, sino que muestra el texto sin formato 3.5.1. [bla bla bla](#blablabla) <br>.

Mi solución es una adición a la solución de @Tum (que es muy simple) para las personas que necesitan una tabla de contenido con 3 niveles o más.

En el segundo nivel, una pestaña simple hará la sangría correctamente para usted. Pero no admite 2 pestañas. En su lugar, debe usar una pestaña y agregar tantas  como sea necesario para alinear el 3er nivel correctamente.

Aquí hay un ejemplo usando 4 niveles (más altos los niveles, horrible se vuelve):

# 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

Esto da el siguiente resultado donde cada elemento de la tabla de contenido es un enlace a su sección correspondiente. Tenga <br>en cuenta también el para agregar una nueva línea en lugar de estar en la misma línea.

Tabla de contenido

1. Título
   1.1. Subtítulo
          1.1.1. Sub-Sub-Título
                    1.1.1.1. Sub-Sub-Sub-Title

Título

Título 1

Subtitular

Título 2

Subtítulo secundario

Título 3

Título 4

Dependiendo de su flujo de trabajo, es posible que desee ver el strapdown

Esa es una bifurcación de la original ( http://strapdownjs.com ) que agrega la generación de la tabla de contenido.

Hay un archivo de configuración de apache en el repositorio (puede que aún no se haya actualizado correctamente) para ajustar el marcado simple sobre la marcha, si prefiere no escribir en archivos html.

No estoy seguro, cuál es la documentación oficial para el descuento. La referencia cruzada se puede escribir solo entre paréntesis [Heading]o con paréntesis vacíos [Heading][].

Ambas obras usan pandoc . Así que creé un script de bash rápido, que reemplazará $ TOC en el archivo md con su TOC. (Necesitará envsubst, que podría no ser parte de su distribución)

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

Si usa Eclipse , puede usar el acceso directo Ctrl+ O(esquema), esto mostrará el equivalente de la tabla de contenido y permitirá buscar en los títulos de las secciones (autocompletar).

También puede abrir la vista Esquema (Ventana -> Mostrar vista -> Esquema) pero no tiene búsqueda de autocompletar.

Use toc.py, que es un pequeño script de Python que genera una tabla de contenido para su descuento.

Uso:

• En su archivo Markdown, agregue <toc>donde desea colocar la tabla de contenido.
• $python toc.py README.md(Use su nombre de archivo Markdown en lugar de README.md )

¡Salud!

He usado https://github.com/ekalinin/github-markdown-toc que proporciona una utilidad de línea de comandos que genera automáticamente la tabla de contenido a partir de un documento de descuento.

Sin complementos, ni macros u otras dependencias. Después de instalar la utilidad, simplemente pegue el resultado de la utilidad en la ubicación del documento donde desea su tabla de contenido. Muy simple de usar.

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

Si su archivo Markdown se va a mostrar en un repositorio en bitbucket.org, debe agregarlo [TOC]en la ubicación donde desea su tabla de contenido. Luego se generará automáticamente. Más información aquí:

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

Hay un script Ruby llamado mdtoc.rb que puede generar automáticamente una tabla de contenido de GFM Markdown, y es similar pero ligeramente diferente a otros scripts publicados aquí.

Dado un archivo de Markdown de entrada como:

# 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 esta tabla de contenido:

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

Véase también mi blog de post sobre este tema.