Bloques de código en Markdown: Guía completa con sintaxis, idiomas y ejemplos

Los bloques de código con delimitadores contienen código fuente de varias líneas en Markdown. El token después de la cerca inicial es una etiqueta de idioma, y solo el renderizador decide qué resalta esa etiqueta.

Esta guía es parte de Herramientas de documentación en 2026: Markdown, LaTeX, PDF y flujos de impresión.

GitHub busca la etiqueta de idioma con Linguist y las palabras clave en languages.yml. Hugo 0.164 entrega la misma etiqueta a Chroma. Una etiqueta que Chroma no conoce sigue siendo un bloque de código, dibujado como texto plano. Los encabezados, tablas y los demás tipos de bloque están en la Hoja de referencia de Markdown.

Resumen de bloques de código en Markdown

Markdown tiene tres formas de marcar código. El código en línea es un tramo dentro de un párrafo. Un bloque indentado y un bloque con delimitadores son ambos de varias líneas, y solo la cerca lleva una etiqueta de idioma.

Un bloque indentado no puede llevar un idioma. CommonMark trata una línea indentada con cuatro espacios como código y no le da nada al resaltador para coincidir, que es la razón por la que una cerca es la forma de usar cuando la muestra debe tener colores.

Una cerca es una línea de al menos tres caracteres de backtick o tres tilde, el código, y luego una línea de cierre del mismo carácter al menos tan larga. La línea de cierre no tiene cadena de información. Para mostrar una cerca de tres backticks dentro de la muestra, abra y cierre con cuatro backticks. Los documentos de bloques de código de GitHub piden una línea en blanco antes y después de la cerca para que el archivo original sea más fácil de leer; la cerca se interpreta igual sin esa línea en blanco.

Cuando la siguiente fuente se almacena como Markdown:

```python
def hello():
    print("Hello, world!")
```

este sitio de Hugo lo renderiza como:

def hello():
    print("Hello, world!")

El código en línea usa la misma regla de backticks a una escala menor. Un par de backticks simples es suficiente para git status. Cuando el tramo mismo contiene un backtick, use dos backticks en cada lado:

`` `código` ``

Resaltado de sintaxis Diff

Una cerca etiquetada como diff es la forma en que se muestra un cambio como texto. El léxico de Chroma de Hugo acepta diff y udiff. GitHub resalta ese mismo identificador de su lista de idiomas.

- vieja línea que será eliminada
+ nueva línea que será agregada
  línea sin cambios

Las líneas que comienzan con - toman el estilo de eliminación, y las líneas que comienzan con + toman el estilo de inserción. Una línea sin ninguno de esos prefijos es texto ordinario en ese léxico. El coloreado es la línea completa. Una palabra cambiada en medio de una línea no se marca por sí sola.

Identificadores de idioma

La primera palabra de la cadena de información es el idioma. Los documentos de Hugo tratan esa palabra como insensible a mayúsculas y minúsculas. Si Chroma no tiene un léxico para ella, Hugo 0.164 emite un <pre><code class="language-…"> plano sin envoltorio de resaltado. Un render local de notalang hizo eso. guessSyntax tiene un valor predeterminado de false, y los documentos de Hugo dicen que solo cinco léxicos implementan la detección automática, por lo que una etiqueta omitida permanece como texto plano en lugar de un idioma adivinado.

El HTML generado desde estas cercas usa la clase language-python y el mismo token. Esa clase es lo que un conversor debe preservar cuando convierte una página resaltada de vuelta a Markdown, que es el mapeo cubierto en Convirtiendo HTML a Markdown con Python.

Los identificadores siguientes son los que se listan para esos idiomas en la tabla de Chroma de Hugo. En un render de Hugo 0.164, cs, yml y markdown también se colorearon, incluso donde la tabla publicada imprime csharp, yaml y md.

Los sitios de GitHub Pages que aún resaltan a través de Jekyll necesitan el identificador en minúsculas. Los propios documentos de GitHub establecen ese requisito por separado del renderizado de github.com.

GitHub también trata algunas cercas como diagramas en lugar de fuente coloreada: mermaid, geojson, topojson y stl. La tabla de Chroma de Hugo no lista mermaid. En un sitio de Hugo, la cerca permanece como texto de fuente hasta que un gancho de render, shortcode o script la dibuja. La Introducción rápida y hoja de referencia de Diagramas Mermaid cubre esa configuración.

Especificando un nombre de archivo

Nada en CommonMark ni en los documentos de bloques de código de GitHub convierte la cadena de información en un nombre de archivo. Las opciones de resaltado de Hugo son pares de llaves tales como {linenos=inline}. No incluyen un campo de nombre de archivo.

Dos puntos después del idioma

Algunos generadores tratan js:app.js como un idioma más un nombre:

```js:app.js
console.log("Hello, world!");
```

GitHub no. Hugo 0.164 mantiene todo el token como la clase del elemento de código (language-js:app.js) y no imprime un nombre de archivo. Qué dialectos añaden significado más allá de la primera palabra es la comparación en GFM vs CommonMark vs Pandoc Markdown.

Nombre encima de la cerca

Una línea de código en línea en negrita encima de la cerca muestra el nombre en GitHub, en este sitio y en otros renderizadores de CommonMark:

**`app.js`**

```js
console.log("Hello, world!");
```

Un encabezado funciona de la misma manera:

#### `app.js`

```js
console.log("Hello, world!");
```

Nombre dentro de la muestra

Un comentario en la primera línea viaja con el código cuando alguien copia el bloque:

```js
// app.js
console.log("Hello, world!");
```

Escapando backticks

Cuatro backticks en el exterior muestran una cerca de tres backticks, que es el patrón para una página que documenta Markdown:

````markdown
```python
# Esta cerca de tres backticks está dentro de una cerca de cuatro backticks
print("hello")
```
````

La cerca de cierre tiene que ser el mismo carácter que la de apertura, y al menos tan larga. Un cierre más corto termina el bloque temprano y deja el resto de la muestra como párrafos ordinarios.

Opciones de resaltado de Hugo

El config.toml de este sitio no tiene un bloque [markup.highlight], por lo que se aplican los valores predeterminados de Hugo: los bloques con delimitadores se resaltan, el estilo es monokai, los estilos se escriben en línea (noClasses true), y los números de línea están apagados. Hugo 0.164 aún colorea una cerca que pide nada más que un idioma, como lo hace la muestra de Python anterior.

Los números de línea y las líneas enfatizadas son opciones de llaves después del idioma. Esta cerca pide números en línea y marca la línea 2:

```python {linenos=inline hl_lines=[2]}
def hello():
    print("Hello, world!")
```

1def hello():
2    print("Hello, world!")

linenos acepta inline, table, true o false. hl_lines es una lista de números de línea o rangos. linenostart establece el primer número mostrado. Las mismas claves son insensibles a mayúsculas y minúsculas. El shortcode highlight las toma como una única cadena entre comillas, y esa cadena aún renderizó números de línea en Hugo 0.164:

{{< highlight python "linenos=true,hl_lines=2" >}}
def hello():
    print("Hello, world!")
{{< /highlight >}}

Para mover los colores a una hoja de estilos, establezca noClasses en false y genere el CSS. Hugo 0.164 acepta --mode y --modeSelector en ese comando:

hugo gen chromastyles --style=monokai --mode=light > assets/css/highlight.css
hugo gen chromastyles --style=monokai --mode=dark --modeSelector > assets/css/highlight-dark.css

--modeSelector aplica alcance a cada regla bajo una clase de nivel superior tal como .dark .chroma. La lista de banderas es hugo gen chromastyles --help.

Cuando la cerca se ve incorrecta

Revise el elemento generado antes de cambiar la muestra. En esta versión de Hugo, un idioma conocido es un div.highlight cuyo elemento de código tiene data-lang establecido en el identificador. Un identificador desconocido es un pre y code desnudos con class="language-…", que es lo que notalang produjo.

Si el nombre app.js falta y la clase es language-js:app.js, se usó la forma de dos puntos. Mueva el nombre a la línea encima de la cerca.

Si las cercas de un propio tutorial aparecen como párrafos sueltos, la cerca exterior tiene la misma longitud que la interior. Alargue la cerca exterior.

Si un comando corto traga el backtick en medio de una oración, el tramo necesita un par de backticks más largo que el carácter que contiene.

Enlaces útiles

• https://www.markdownguide.org/extended-syntax/
• https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks
• https://gohugo.io/content-management/syntax-highlighting/