Cómo mostrar una tabla de contenidos con Markdown

Markdown no creará una tabla de contenidos ni incorpora ninguna función para hacerlo. Esto no significa que no puedas crearla manualmente o mediante otros medios.

Existen herramientas como Markdeep que te dan la opción de insertar una tabla de contenidos automáticamente, aunque no se trata de una funcionalidad que incluyan todos los editores.

Con Markdown existen dos formas de agregar una tabla de contenidos. La primera de ellas consiste en crear una simple lista de enlaces, siempre y cuando tu editor soporte o bien la inserción de IDs de encabezados o bien HTML. La otra forma consiste en usar un script que genere la tabla automáticamente, siempre y cuando vayas a mostrar el proyecto en una web.

Crea una tabla de contenidos con Markdown

Para mostrar una tabla de contenidos con Markdown basta con que muestres una lista de enlaces. Cada enlace enlazará con el identificador de los encabezados que quieras motrar, usando la sintaxis #identificador:

- [Encabezado 1](#identificador1)
- [Encabezado 2](#identificador2)
- [Encabezado 3](#identificador3)

Si tu editor o el visualizador o navegador donde vayas a mostrar los enlaces soporta los identificadores de encabezado, entonces deberías ver el siguiente resultado.

• Encabezado 1
• Encabezado 2
• Encabezado 3

Crea una Tabla de contenidos con HTML

Si tu aplicación soporta el uso de HTML puedes crear la tabla de contenidos usando directamente HTML. Por ejemplo, puedes motrar una lista de enlaces usando la etiqueta ul y agregar cada enlace en el interior de una etiqueta li:

<ul>
    <li>
        <a href="#identificador1">Encabezado 1</a>
    </li>
    <li>
        <a href="#identificador2">Encabezado 2</a>
    </li>
    <li>
        <a href="#identificador3">Encabezado 3</a>
    </li>
</ul>

Deberías ver también una lista de enlaces como tabla de contenidos:

• Encabezado 1
• Encabezado 2
• Encabezado 3

Crea una tabla de contenidos con JavaScript

También es posible automatizar la creación de la tabla de contenidos usando JavaScript. Para ello debes agregar un div vacío en la parte de tu documento donde quieres que se muestre la lista y luego insertar la tabla de contenidos en la lista.

En el siguiente ejemplo agregamos un div al que le asignamos tabla_contenidos como identifiador:

<div id="tabla_contenidos">
</div>

Luego, mediante JavaScrit, obtendremos todos los encabezados del documento y los agregaremos al div anterior:

// Referencia a la tabla de contenidos
const tablaContenidos = document.querySelector("#tabla_contenidos");

// Obtenemos los encabezados
const encabezados = document.querySelectorAll("h2, h3");

// Recorremos los enlaces
encabezados.forEach(function callback(encabezado) {

  const identificador = encabezado.getAttribute("id");

  const enlace = document.createElement('a');
  enlace.setAttribute('target', '_self');
  enlace.setAttribute("href", "#" + identificador);

  enlace.innerHTML = encabezado.textContent.replace(/ *\([^)]*\) */g, '');
  tablaContenidos.append(enlace);
});

Primero hemos obtenido en la constante tablaContenidos una referencia al div cuyo atributo id es tabla_contenidos. Luego hemos obtenidos los encabezados de segundo y tercer nivel en la constante encabezados. Si quieres, puedes obtener más niveles.

Luego hemos usado un bucle foreach para recorrer los encabezados. Si no conoces este bucle, puedes consultar mi guía de bucles en JavaScript.

En el interior del bucle hemos obtenido el identificador de cada uno de los enlaces en la constante identificador. Luego creamos un enlace usando el método document.createElement y le asignamos los siguientes atributos:

• target: Asignamos el valor _self, ya que el enlace es una referencia al propio documento.
• href: Asignamos # junto con el el valor de la etiqueta id del encabezado.

Luego hemos usado le método innerHTML para agregar el título del encabezado al texto del enlace, ya que es el texto que se mostrará. Finalmente usamos el método append para agregar el enlace a la tabla de contenidos.

Si tus enlaces no tienen id, también puedes asignarlos automáticamente en función del título de cada encabezado:

identificador = encodeURIComponent(encabezado.textContent.toLowerCase().replace(/\s+/g, '-'));
encabezado.setAttribute("id", identificador);

Esto ha sido todo.