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

Aquí reviso las opciones de bloques de código en Markdown: cómo especificar el lenguaje de programación, el formato de diferencias (diff) y el nombre del archivo en el bloque de código.

Esta guía forma parte de nuestro centro de recursos sobre Herramientas de Documentación en 2026: Markdown, LaTeX, PDF y Flujos de Trabajo de Impresión.

Resumen de los Bloques de Código en Markdown

Los bloques de código en Markdown muestran código o texto preformateado dentro de documentos Markdown, preservando el formato y habilitando opcionalmente la resaltado de sintaxis. Existen dos tipos principales de formato de código en Markdown: código en línea y bloques de código.

Tipos de Bloques de Código en Markdown

Diferencias Clave

• El código en línea utiliza comillas angulares simples (`) y se destina a fragmentos de código cortos dentro de una oración.
• Los bloques de código indentados utilizan cuatro espacios o una tabulación al principio de cada línea. No admiten resaltado de sintaxis y son poco comunes en el Markdown moderno.
• Los bloques de código delimitados utilizan triples comillas angulares (```) o tildes (~~~) antes y después del código. Este es el método preferido, especialmente en plataformas como GitHub, porque:
  • Son más fáciles de leer y escribir.
  • Puede especificar el lenguaje de programación inmediatamente después de las comillas angulares de apertura para el resaltado de sintaxis.
  • Preservan el formato y admiten código multilínea.

Ejemplo de un bloque de código delimitado con resaltado de sintaxis:

Cuando tenemos el siguiente texto formateado en Markdown:

```python
def hello():
    print("¡Hola, mundo!")
```

El resultado renderizado se ve así:

def hello():
    print("¡Hola, mundo!")

Mejores Prácticas para Bloques de Código en Markdown

• Use bloques de código delimitados (triple comillas angulares) para código multilínea para garantizar claridad y compatibilidad entre plataformas.
• Especifique el lenguaje después de las comillas angulares de apertura para el resaltado de sintaxis (por ejemplo, ```python).
• Use código en línea para fragmentos cortos o comandos dentro del texto.
• Evite los bloques de código indentados a menos que sea necesario para compatibilidad con versiones anteriores, ya que no admiten resaltado de sintaxis y pueden ser menos legibles.
• Coloque una línea en blanco antes y después de los bloques de código delimitados para mejorar la legibilidad en el Markdown sin procesar.

Características Especiales

• Algunas plataformas admiten identificadores de lenguaje adicionales, como diff para mostrar cambios en el código, lo que resalta las líneas añadidas o eliminadas en las revisiones de código.
• Para mostrar comillas angulares dentro de un bloque de código, envuelva el bloque en un número mayor de comillas angulares (por ejemplo, cuatro comillas angulares para mostrar tres dentro).

Resumen de Referencia Rápida

Use bloques de código delimitados con un identificador de lenguaje para la mejor legibilidad y resaltado de sintaxis. Reserve el código en línea para fragmentos cortos y evite los bloques indentados a menos que sea necesario para la compatibilidad.

Los bloques de código se combinan naturalmente con tablas en Markdown para construir documentación técnica bien estructurada.

Resaltado de Sintaxis de Diferencias (Diff)

El resaltado de sintaxis de diferencias le permite mostrar cambios en el código de manera clara, lo cual es útil en documentación, revisiones de código y blogs técnicos.

• Use bloques de código delimitados con triples comillas angulares (```) para iniciar y finalizar su bloque.
• Especifique diff como identificador de lenguaje inmediatamente después de las comillas angulares de apertura.

Ejemplo:

- línea antigua que será eliminada
+ nueva línea que será añadida
  línea sin cambios

• Las líneas que comienzan con - se resaltan como eliminaciones (generalmente en rojo).
• Las líneas que comienzan con + se resaltan como adiciones (generalmente en verde).
• Las líneas sin prefijo no tienen resaltado especial.

Mejores prácticas:

• Coloque una línea en blanco antes y después de su bloque de código para una mejor legibilidad en el Markdown sin procesar.
• Tenga en cuenta que el resaltado de diff solo colorea líneas enteras basándose en el carácter inicial; no resalta cambios en línea dentro de una línea.

Consejo: El resaltado de diff es ampliamente compatible en GitHub, GitLab y la mayoría de los renderizadores de Markdown, lo que lo convierte en una opción confiable para comunicar cambios en el código.

Lenguajes Soportados para el Resaltado de Sintaxis

El conjunto exacto de lenguajes soportados depende del renderizador o plataforma que utilice. Markdown pasa el identificador de lenguaje al motor de renderizado, que aplica el resaltado de sintaxis apropiado. Esto es importante al convertir HTML a Markdown con Python, ya que las etiquetas <code> que llevan atributos de clase de lenguaje (por ejemplo, class="language-python") mapean directamente a estos identificadores en el bloque delimitado.

Lenguajes comúnmente soportados en plataformas principales (GitHub, VS Code, Bitbucket, Docusaurus, ReadMe):

• Web y Scripting: javascript (js), typescript (ts), html, css, json, xml, yaml, shell/bash (sh, bash, shell, zsh)
• Programación: python (py), java, c, cpp (c++), csharp (c#), php, ruby, go, rust, scala, swift, kotlin, objective-c
• Datos y Consultas: sql, r, matlab
• Marcado y Configuración: markdown, ini, toml, dockerfile, makefile
• Especial: diff, mermaid, geojson, topojson, stl (para diagramas y visualizaciones de datos en GitHub) — el identificador mermaid en particular habilita el renderizado completo de diagramas en plataformas compatibles; consulte la Guía de Inicio Rápido y Referencia de Diagramas Mermaid para una referencia completa de sintaxis y guía de configuración de Hugo
• Otros: jsx, tsx, perl, lua, julia, dart, groovy, powershell, vb, elixir, erlang, fortran, haskell, lisp, scheme, y muchos más

Cómo especificar un lenguaje:

```python
def hello():
    print("¡Hola, mundo!")
```

Identificadores de lenguaje soportados en la mayoría de los renderizadores:

Nota: La mayoría de los renderizadores no distinguen entre mayúsculas y minúsculas en los nombres de los lenguajes. Si utiliza un identificador no soportado, el bloque de código se renderiza como texto sin formato.

Cómo encontrar la lista completa de lenguajes soportados:

• GitHub: Utiliza Linguist, soportando cientos de lenguajes.
• VS Code y muchos renderizadores web: Utilizan highlight.js o Pygments; consulte su documentación para listas exhaustivas.
• Bitbucket: Se refiere a los modos de CodeMirror y los analizadores léxicos de Pygments.

Especificar un Nombre de Archivo en un Bloque de Código Markdown

Mostrar el nombre del archivo junto a un bloque de código ayuda a los lectores a identificar a qué archivo pertenece un fragmento. El soporte varía según la plataforma.

1. Nombre de Archivo en la Etiqueta del Bloque de Código (Sintaxis Meta)

Algunos motores de Markdown (ciertos generadores de sitios estáticos y plataformas de documentación) admiten una sintaxis meta donde se anexa el nombre del archivo después del lenguaje, separado por dos puntos:

```js:app.js
console.log("¡Hola, mundo!");
```

Esto muestra el nombre del archivo arriba o junto al bloque de código. El renderizador de Hugo de este sitio no lo soporta:

console.log("¡Hola, mundo!");

Nota: Esto no es compatible con Markdown con sabor de GitHub.

2. Título Manual o Código en Línea para el Nombre de Archivo

Para una compatibilidad universal (incluyendo GitHub, Stack Overflow y la mayoría de los renderizadores de Markdown), coloque el nombre del archivo sobre el bloque de código usando código en línea en negrita:

**`app.js`**

```js
console.log("¡Hola, mundo!");
```

O con un encabezado:

#### `app.js`

```js
console.log("¡Hola, mundo!");
```

Esto funciona en todas partes y asocia visualmente el nombre del archivo con el bloque de código.

3. Nombre de Archivo como Comentario Dentro del Código

Incluya el nombre del archivo como un comentario dentro del propio bloque de código:

```js
// app.js
console.log("¡Hola, mundo!");
```

Esto es especialmente útil cuando desea que el nombre del archivo sea visible al copiar el código.

Resumen de Compatibilidad

Use código en línea en negrita sobre el bloque de código para máxima compatibilidad y considere un comentario dentro del código para mayor claridad al compartir entre plataformas.

Escapar Comillas Angulares Dentro de Bloques de Código

Para mostrar comillas angulares dentro de un bloque de código — por ejemplo, al escribir documentación sobre Markdown mismo — anide el bloque en un número mayor de comillas angulares:

````markdown
```python
# Este límite de triple comilla angular está dentro de un límite de cuatro comillas angulares
print("hola")
```
````

Usar cuatro comillas angulares como el límite exterior le permite mostrar ejemplos de triples comillas angulares dentro, lo cual es útil para tutoriales y guías de referencia rápida de Markdown.

Específico de Hugo: El Shortcode de Resaltado

Si utiliza Hugo, el shortcode integrado highlight ofrece más control que los bloques delimitados simples, incluyendo números de línea y líneas resaltadas:

{{< highlight python "linenos=true,hl_lines=2 4" >}}
def greet(name):
    print(f"¡Hola, {name}!")

greet("world")
{{< /highlight >}}

Opciones:

• linenos=true — mostrar números de línea
• hl_lines=2 4 — resaltar las líneas 2 y 4
• linenostart=10 — comenzar la numeración de líneas en 10

Esto es particularmente útil en tutoriales o documentación donde desea llamar la atención sobre líneas específicas. Consulte la Guía de Referencia Rápida de Markdown para más características de formato y la Guía de Referencia Rápida de Hugo para una referencia más amplia sobre comandos y plantillas de Hugo.

Enlaces Útiles

• https://www.markdownguide.org/extended-syntax/
• https://docs.readme.com/rdmd/docs/code-blocks