Markdown para crear páginas y tabla de contenido?


359

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.


2
si desea utilizar una herramienta javascript / node.js, intente marcado-toc
jonschlinkert

@jonschlinkert ¡Deberías enviar eso como respuesta! Actualmente, las respuestas solo sugieren herramientas que no son gratuitas o Python. No es realmente un gran conjunto de opciones.
Domi

8
Quizás debería mencionar que en LaTeX esto se logra con \tableofcontents. Si la rueda se va a reinventar, sería preferible copiar las partes buenas.
Eero Aaltonen


Del mismo modo, reStructuredText tiene una directiva incorporada para la tabla de contenido que, en la forma más simple, se ve como justa .. contents::.
Saaj

Respuestas:


37

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 .


17
MultiMarkdown Composer es solo para MacOS
chmike

1
Enlace de TOC de trabajo de Python Markdown: python-markdown.github.io/extensions/toc
John

2
La aplicación no está disponible en la región del Reino Unido.
kenorb

La extensión TOC produce tocs HTML, no Markdown. Es notable que esto sea difícil.
rjurney

396

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) 

10
El tercer ejemplo anterior no funciona. ## Example ## "Example2" ## Third Example<a name="third-example" /> es la única forma en que podría tragar espacios hasta ahora. ¿Seguramente la tercera etiqueta se interpretaría como - #Third- seguido de un espacio - luego la palabra Ejemplo - en su fragmento de arriba? Los guiones no funcionan en absoluto. Gracias
twobob

El ejemplo está ahí para servir como ejemplo para más de una palabra. Todas las palabras se dividen en mayúsculas y sin espacios.
Rick

66
Funciona bien en RStudio. Sólo quiero añadir que las diéresis alemanas por ejemplo, u necesidad de escribir sin diéresis es decir, en el ancla1. [Einführung](#einfuhrung)
steinbock

44
Los anclajes no se crean automáticamente para encabezados en Bitbucket v4.5.2
Mike Rylander

1
Ese cuarto ejemplo es lo que estaba buscando. ¡Gracias!
kenecaswell

221

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


23
Me gusta poner la etiqueta de anclaje en la línea sobre el encabezado, de modo que cuando se hace clic en el enlace, el encabezado aparece en la página.
mgarey 05 de

44
Este fue el único útil para mí. Con títulos largos, es imposible hacerlo sin etiquetas de anclaje.
Matt Fletcher

Esto es realmente lindo Comencé a colocar una Tabla de contenido en todos mis cuadernos Jupyter para navegar rápidamente entre las secciones.
jackdbd

@mgarey Solo ponga el ancla primero:## <a name="foo" /> Foo
tobias_k

40

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.


77
Nota: Acabo de descubrir que usando el VSCode de stock puede hacer enlaces de marcado a encabezados: [Section Foo](#foo-header-title)e incluso funciona fuera del modo de vista previa (es decir, en el marcado simple).
kitsu.eb

44
Otra alternativa para VSCode es vscode-markdown, que tiene múltiples características, incluido ToC
Ciprian Tomoiagă

26

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

¡Excelente! Solo una nota, es posible que desee agregar ifndef, includey endif, entre otras directivas de preprocesador, a la lista de palabras prohibidas. Además, definir la lista fuera del alcance del bucle evita tener que volver a establecerla con cada iteración. Además, esto recogerá comentarios de cualquier idioma que use la #sintaxis de comentarios, incluido Ruby, lo que no es bueno. Estoy dispuesto a editar si lo desea. Sin embargo, este es un gran comienzo y funcionó bien para mis propósitos. ¡Muchas gracias!
Jeff Klein

Esto solo funciona con encabezados atx (es decir, aquellos que comienzan con #), no con encabezados de texto (subrayados).
gozzilli

gracias por esto, si estás usando esto para redcarpet on rails, deberías ir con title.parameterizeel href, ¡gracias!
Alexis

25

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.


`` <div id = ... `no es reconocido por MarkdownPad2 (Windows)
chmike

Solo funciona en la misma carpeta, tampoco funciona para títulos de texto.
gozzilli

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


11

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

vim-markdown-toc

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


10

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



7

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

Esto es genial. Valdría la pena volver a escribirlo como un script adecuado con el nombre del archivo como argumento, y tal vez con el manejo de las subsecciones.
MasterScrat

6

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

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


6

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

2. Formato BBCode


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


5

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.


5

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




4

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:


2

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


2

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 &nbsp;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

Sub-Sub-Sub-Title

Título 4


1

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.


1

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

1

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.


1

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!


Tu guión es agradable pero no crea un ancla antes de cada título. Necesario al menos en bitbucket.
Paul Rougieux

1

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 -


1

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.

Al usar nuestro sitio, usted reconoce que ha leído y comprende nuestra Política de Cookies y Política de Privacidad.
Licensed under cc by-sa 3.0 with attribution required.