Cómo numerar las líneas de un bloque de código con Markdown

Mostrar números de línea junto a un bloque de código es muy útil en tutoriales y documentación técnica, ya que permite referirse a una línea concreta (por ejemplo, "fíjate en la línea 7") sin necesidad de recortar el código en fragmentos. El problema es que Markdown estándar no contempla esta funcionalidad: depende por completo del procesador o de la plataforma donde se publique el documento.

A continuación verás las opciones más habituales según el entorno donde estés trabajando, desde las que usan extensiones específicas hasta los trucos más portátiles.

Numeración automática en GitHub y GitLab

Tanto GitHub como GitLab no muestran números de línea en los bloques de código dentro de un archivo Markdown renderizado (README, issues, comentarios). La numeración solo aparece cuando se visualiza el código en su vista de archivo, no cuando se incrusta dentro de un Markdown.

Si quieres referirte a una línea concreta de un archivo del repositorio, lo habitual es enlazar directamente a la vista del archivo con el ancla de la línea correspondiente. Por ejemplo, en GitHub se hace añadiendo #L7 al final de la URL del archivo.

Numeración con Prism y plataformas que lo usan

Prism es uno de los resaltadores de sintaxis más populares en sitios estáticos y blogs. Dispone de un plugin específico llamado line-numbers que añade los números de línea de forma automática.

En el siguiente ejemplo activamos los números de línea añadiendo la clase line-numbers al <pre>:

<pre class="line-numbers"><code class="language-js">
function suma(a, b) {
  return a + b;
}
</code></pre>

Para que funcione, el plugin de Prism debe estar incluido en el sitio donde se publica el contenido. Es un patrón común en blogs y sitios de documentación con Jekyll, Hugo, Astro o Next.js que usen Prism.

Numeración con highlight.js

highlight.js es otro resaltador muy popular. La versión base no incluye números de línea por defecto, pero existen plugins de terceros como highlightjs-line-numbers.js que añaden la funcionalidad. La activación se hace por JavaScript después de cargar la librería, así que es algo más invasivo que con Prism.

Numeración con Pandoc

Si conviertes el Markdown a HTML, PDF o LaTeX con Pandoc, puedes activar los números de línea directamente en los atributos del bloque de código, usando su sintaxis extendida.

En el siguiente ejemplo activamos la numeración con la opción .numberLines:

```{.javascript .numberLines}
function suma(a, b) {
  return a + b;
}
```

Pandoc generará un bloque con los números de línea a la izquierda en el formato de salida correspondiente. Puedes incluso establecer el número inicial con el atributo startFrom.

Numeración manual como último recurso

Si tu plataforma no soporta ninguna de las opciones anteriores y necesitas referirte a líneas concretas, queda el recurso de añadir los números a mano dentro del propio bloque de código. Es feo y propenso a errores, pero funciona en cualquier visor.

En el siguiente ejemplo numeramos las líneas a mano:

1  function suma(a, b) {
2    return a + b;
3  }

El principal inconveniente es que si añades o quitas líneas, tendrás que renumerar todo manualmente. Solo es recomendable para bloques cortos en los que la numeración aporta algo concreto.

Esto ha sido todo.