Bloques de código en Markdown: vallas y resaltado de sintaxis

Si escribes documentación técnica, el bloque de código es el elemento que más vas a usar después de los encabezados. Hay dos sintaxis y una de ellas es claramente mejor.

Bloques con vallas (recomendado)

Encierra el código entre dos líneas de tres acentos graves ```:

```
function saludar(nombre) {
  return `Hola, ${nombre}`;
}
```

Resultado:

function saludar(nombre) {
  return `Hola, ${nombre}`;
}

Dentro del bloque nada se interpreta: los asteriscos no ponen negrita, las almohadillas no crean encabezados y los guiones no crean listas. El texto sale literalmente como lo escribiste, respetando espacios y saltos de línea.

Esta sintaxis se llama fenced code block (bloque vallado) y viene de GitHub Flavored Markdown, aunque hoy la admite prácticamente todo, incluido CommonMark.

También sirve la virgulilla

Tres virgulillas ~~~ funcionan igual que los acentos graves:

~~~
Esto también es un bloque de código
~~~

Es útil cuando el propio código contiene acentos graves y no quieres complicarte. Por lo demás, los acentos graves son la convención dominante.

Resaltado de sintaxis

Escribe el nombre del lenguaje justo después de los acentos graves de apertura y el procesador coloreará el código:

```javascript
const total = precios.reduce((a, b) => a + b, 0);
```

const total = precios.reduce((a, b) => a + b, 0);

Y en Python:

```python
total = sum(precios)
```

total = sum(precios)

Los identificadores más habituales:

Lenguaje	Identificadores válidos
JavaScript	javascript, js
TypeScript	typescript, ts
Python	python, py
Bash / shell	bash, sh, shell
HTML	html
CSS	css
JSON	json
YAML	yaml, yml
SQL	sql
Markdown	markdown, md
Texto sin resaltar	text, plain

Si el identificador no se reconoce, el bloque se muestra sin colorear: no rompe nada.

Indica siempre el lenguaje. Cuesta cuatro caracteres y mejora mucho la lectura. Además, algunos procesadores lo usan para el botón de “copiar” y para detectar el idioma en las búsquedas dentro del repositorio.

Bloques con sangría (la forma antigua)

El Markdown original de 2004 no tenía vallas. Los bloques de código se creaban sangrando el texto cuatro espacios:

    Esto es un bloque de código
    creado con sangría

Resultado:

Esto es un bloque de código
creado con sangría

Funciona, y es la única forma disponible en procesadores muy antiguos, pero tiene tres inconvenientes serios:

• No admite resaltado de sintaxis. No hay dónde indicar el lenguaje.
• Hay que sangrar cada línea. Insufrible en bloques largos.
• Choca con las listas. Dentro de una lista, cuatro espacios ya significan “anidar”, así que la sangría se vuelve ambigua.

Salvo que tengas una razón concreta, usa vallas.

Anidar bloques dentro de listas

Para meter un bloque de código dentro de un elemento de lista, sangra las vallas al mismo nivel que el texto del elemento y deja una línea en blanco antes:

1. Instala las dependencias:

    ```bash
    npm install
    ```

2. Arranca el servidor:

    ```bash
    npm run dev
    ```

Resultado:

1. Instala las dependencias:

   npm install

2. Arranca el servidor:

   npm run dev

Si el bloque sale fuera de la lista o la numeración se reinicia, casi siempre es que falta sangría en las vallas.

Mostrar un bloque dentro de otro bloque

Es la situación de esta misma página: ¿cómo enseñas la sintaxis de un bloque de código si los acentos graves se interpretan?

La solución es usar más acentos graves en el exterior que en el interior. Con cuatro fuera y tres dentro:

````
```
código de ejemplo
```
````

La regla es general: la valla exterior necesita al menos un acento grave más que la valla interior más larga que contenga.

Código en línea

Para marcar una palabra suelta dentro de un párrafo —un nombre de archivo, un comando, una variable— no uses un bloque: usa código en línea con un solo acento grave.

Ejecuta `npm install` antes de continuar.

Ejecuta npm install antes de continuar.

Errores frecuentes

Vallas desiguales. El número de acentos graves de cierre debe ser igual o mayor que el de apertura. Si abres con tres y cierras con dos, el bloque no se cierra y se come el resto del documento.

Espacios antes de las vallas. Una valla sangrada más de tres espacios (fuera de una lista) deja de ser valla.

Olvidar cerrar. Es el fallo más destructivo: todo el contenido posterior queda dentro del bloque. Si de repente media página se ve en monoespaciado, busca una valla sin cerrar.

Usar comillas en vez de acentos graves. El carácter es ` (acento grave o backtick), no ' ni ´. En el teclado español está a la izquierda del 1, y hay que pulsarlo dos veces o seguido de espacio porque es una tecla muerta.

Compatibilidad

Sintaxis	Original	CommonMark	GFM
Sangría de 4 espacios	✅	✅	✅
Vallas ```	❌	✅	✅
Vallas ~~~	❌	✅	✅
Resaltado por lenguaje	❌	❌	✅

El resaltado depende del procesador, no de la especificación: GitHub, GitLab, Obsidian y VS Code lo hacen; otros lo ignoran silenciosamente sin romper nada.

Pruébalo

Comprueba cómo queda el resaltado en el previsualizador de Markdown, o convierte el documento a HTML para ver las etiquetas <pre><code> con su clase de lenguaje.