Bloques de Código Markdown: Guía Completa con Sintaxis, Lenguajes y Ejemplos

Aquí estoy revisando opciones de bloques de código en Markdown—cómo especificar el lenguaje de programación, el formato de diferencias y el nombre de archivo del bloque de código.

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

Visión general 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, manteniendo el formato y habilitando opcionalmente la resaltación de sintaxis. Hay dos tipos principales de formateo 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

• Código en línea utiliza comillas invertidas simples (`) y se usa para fragmentos cortos dentro de una oración.
• Bloques de código con sangría utilizan cuatro espacios o una tabulación al inicio de cada línea. No admiten resaltado de sintaxis y son poco comunes en Markdown moderno.
• Bloques de código delimitados utilizan tres comillas invertidas (```) o tilde (~~~) 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.
  • Puedes especificar el lenguaje de programación inmediatamente después de las comillas invertidas para resaltado de sintaxis.
  • Preservan el formato y admiten código de varias líneas.

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

Cuando tenemos el siguiente texto formateado en Markdown:

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

La salida renderizada se ve así:

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

Mejores prácticas para bloques de código en Markdown

• Usa bloques de código delimitados (tres comillas invertidas) para código de varias líneas para garantizar claridad y compatibilidad en diferentes plataformas.
• Especifica el lenguaje después de las comillas invertidas iniciales para resaltado de sintaxis (por ejemplo, ```python).
• Usa código en línea para fragmentos cortos o comandos dentro del texto.
• Evita bloques de código con sangría a menos que sea necesario para la compatibilidad con versiones anteriores, ya que no admiten resaltado de sintaxis y pueden ser menos legibles.
• Coloca una línea en blanco antes y después de los bloques de código delimitados para mejorar la legibilidad en Markdown crudo.

Funciones 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 revisiones de código.
• Para mostrar comillas invertidas dentro de un bloque de código, envuelve el bloque en un número mayor de comillas invertidas (por ejemplo, cuatro comillas invertidas para mostrar tres dentro).

Resumen rápido

Usa bloques de código delimitados con un identificador de lenguaje para la mejor legibilidad y resaltado de sintaxis. Reserva código en línea para fragmentos cortos y evita bloques con sangría 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 te permite mostrar cambios en el código claramente — útil en documentación, revisiones de código y blogs técnicos.

• Usa bloques de código delimitados con tres comillas invertidas (```) para iniciar y finalizar tu bloque.
• Especifica diff como identificador de lenguaje inmediatamente después de las comillas invertidas iniciales.

Ejemplo:

- línea antigua que se eliminará
+ línea nueva que se añadirá
  línea sin cambios

• Líneas que comienzan con - se resaltan como eliminaciones (normalmente en rojo).
• Líneas que comienzan con + se resaltan como adiciones (normalmente en verde).
• Líneas sin prefijo no se resaltan especialmente.

Mejores prácticas:

• Coloca una línea en blanco antes y después de tu bloque de código para una mejor legibilidad en Markdown crudo.
• Tenga en cuenta que el resaltado de diferencias solo colorea líneas completas basándose en el carácter inicial; no resalta cambios en línea.

Consejo: El resaltado de diferencias está ampliamente admitido en GitHub, GitLab y la mayoría de los renderizadores de Markdown, lo que lo convierte en una elección confiable para comunicar cambios en el código.

Lenguajes admitidos para resaltado de sintaxis

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

Lenguajes comúnmente admitidos 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
• Markup y configuración: markdown, ini, toml, dockerfile, makefile
• Especiales: diff, mermaid, geojson, topojson, stl (para diagramas y visualizaciones de datos en GitHub)
• 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("Hello, world!")
```

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

Nota: La mayoría de los renderizadores son insensibles a mayúsculas y minúsculas para los nombres de lenguaje. Si usa un identificador no admitido, el bloque de código se renderiza como texto plano.

Cómo encontrar la lista completa de lenguajes admitidos:

• GitHub: Usa Linguist, que admite cientos de lenguajes.
• VS Code y muchos renderizadores web: Usan highlight.js o Pygments—consulte su documentación para listas exhaustivas.
• Bitbucket: Se refiere a CodeMirror modes y a los analizadores de Pygments.

Especificar un nombre de archivo en un bloque de código en 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. La compatibilidad varía según la plataforma.

1. Nombre del 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 agrega el nombre del archivo después del lenguaje, separado por un punto y coma:

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

Esto muestra el nombre del archivo encima o junto al bloque de código. El renderizador de Hugo de este sitio no admite esta función:

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

Nota: Esto no está admitido en Markdown de sabor GitHub.

2. Encabezado o código en línea manual del nombre del archivo

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

**`app.js`**

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

O con un encabezado:

#### `app.js`

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

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

3. Nombre del archivo como comentario dentro del código

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

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

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

Resumen de compatibilidad

Use código en línea en negrita encima del bloque de código para la máxima compatibilidad, y considere un comentario dentro del código para claridad al compartir en plataformas.

Escapar comillas invertidas dentro de bloques de código

Para mostrar delimitadores de comillas invertidas dentro de un bloque de código — por ejemplo, cuando escribe documentación sobre Markdown mismo — anide el bloque en un número mayor de comillas invertidas:

````markdown
```python
# Este delimitador de comillas invertidas triple está dentro de un delimitador de comillas invertidas cuádruple
print("hello")
```
````

Usar cuatro comillas invertidas como delimitador externo le permite mostrar ejemplos de delimitadores de comillas invertidas triples dentro, lo cual es útil para tutoriales y hojas de referencia de Markdown.

Específico de Hugo: El shortcode de resaltado

Si usa 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"Hello, {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 — iniciar el numerado de líneas en 10

Esto es especialmente útil en tutoriales o documentación donde quiera llamar la atención a líneas específicas. Consulte la Hoja de referencia de Markdown para más características de formateo, y la Hoja de referencia de Hugo para una referencia más amplia de comandos y plantillas de Hugo.

Enlaces útiles

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