Bloques de código Markdown - hoja de referencia y ejemplos de cómo usarlos

Aquí estoy revisando opciones de bloques de código en Markdown.

Bloques de código en Markdown

Los bloques de código en Markdown son una forma de mostrar 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 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 invertidas simples (`) y se usa para fragmentos cortos dentro de una oración.
• Los 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 menos comunes en Markdown moderno.
• Los 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 el resaltado de sintaxis.
  • Conservan el formato y admiten código de varias líneas.

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

Cuando tenemos el siguiente texto formateado en Markdown:

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

Entonces el texto renderizado se verá así:

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

Mejores prácticas para usar 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 todas las plataformas.
• Especifica el lenguaje después de las comillas invertidas para el 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 antiguas, 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 adicionales de lenguaje, como diff para mostrar cambios en el código, lo que puede resaltar líneas agregadas 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 comillas invertidas).

OutTake

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

Resaltado de sintaxis de diff

Para usar eficazmente el resaltado de sintaxis de diff en bloques de código en Markdown, sigue estos pasos:

• 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 de apertura. Esto activa el resaltado de sintaxis para diferencias, similar a lo que ves en mensajes de commit de Git o solicitudes de extracción.

Ejemplo:

- línea antigua que se eliminará
+ línea nueva que se agregará
 línea sin cambios

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

Mejores prácticas:

• Usa este formato para comunicar claramente cambios en el código, correcciones o sugerencias en la documentación, revisiones de código o blogs técnicos.
• Coloca una línea en blanco antes y después de tu bloque de código para mejorar la legibilidad en Markdown crudo.
• Ten en cuenta que el resaltado de diff solo colorea líneas completas según el carácter inicial; no resalta cambios en línea.

Consejo:
Este método es ampliamente admitido en plataformas como GitHub, GitLab y muchos renderizadores de Markdown, lo que lo convierte en una opción confiable para compartir cambios en el código visualmente.

Lenguajes admitidos

Los bloques de código en Markdown admiten una amplia variedad de lenguajes para el resaltado de sintaxis, pero el conjunto exacto de lenguajes admitidos depende del renderizador o plataforma que estés usando. El Markdown en sí mismo no define cuáles son los lenguajes admitidos; simplemente pasa el identificador de lenguaje al motor de renderizado, que luego aplica el resaltado de sintaxis adecuado. Los bloques de código delimitados en sí mismos no definen un conjunto fijo de lenguajes de programación oficialmente admitidos. En cambio, la lista de lenguajes admitidos depende del renderizador de Markdown o plataforma que estés usando (como GitHub, GitLab, VS Code, Typora, Quarto, etc.).

Lenguajes comúnmente admitidos en plataformas principales (como GitHub, VS Code, Bitbucket, Docusaurus y ReadMe) incluyen:

• Web & Scripting: javascript (js), typescript (ts), html, css, json, xml, yaml, shell/bash (sh, bash, shell, zsh)
• Programación: python (py), java, c, c++, c#, php, ruby, go, rust, scala, swift, kotlin, objective-c
• Datos & Consultas: sql, r, matlab
• Markup & Config: 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: Usa el nombre del lenguaje inmediatamente después de las tres comillas invertidas de apertura:

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

Los siguientes lenguajes son ampliamente admitidos en LA MAYORÍA DE LOS RENDERIZADORES DE MARKDOWN:

Nota: El identificador real puede variar (por ejemplo, js vs. javascript). La mayoría de los renderizadores son insensibles al caso para los nombres de lenguaje.

Encontrar la lista completa de lenguajes admitidos:

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

Puntos clave:

• La mayoría de las plataformas admiten todos los lenguajes principales de programación, scripting y markup.
• Algunas plataformas también admiten formatos de diagramas y datos (como mermaid, geojson).
• El identificador de lenguaje suele ser insensible al caso, pero debe estar en minúsculas para la mejor compatibilidad.
• Si usas un identificador de lenguaje no admitido, el bloque de código se renderizará como texto plano.

Especificar nombre de archivo en bloque de código en Markdown

Para especificar un nombre de archivo en un bloque de código en Markdown, tienes varias opciones, pero el método depende de la plataforma y el renderizador:

1. Nombre de archivo en la etiqueta del bloque de código (sintaxis meta)

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

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

Esto mostrará el nombre del archivo (por ejemplo, app.js) encima o junto al bloque de código, según el renderizador. Y este sitio web’ renderizador hugo no lo hace:

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

Nota: Esto no está admitido en todas las plataformas (por ejemplo, el Markdown con sabor a GitHub no admite actualmente esta función).

2. Encabezado o código en línea en negrita con el nombre del archivo

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

**`app.js`**

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

O:

#### `app.js`

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

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

3. Nombre del archivo como comentario en el código

También puedes incluir el nombre del archivo como comentario dentro del bloque de código mismo:

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

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

Resumen y mejor práctica

Usa un encabezado o código en línea en negrita encima del bloque de código para la máxima compatibilidad, y considera agregar un comentario dentro del código para claridad al compartir en diferentes plataformas.

Enlaces útiles

• Hoja de trucos de Markdown - estructuras y comandos más útiles
• Hoja de trucos de Hugo
• Hoja de trucos de Bash - comandos de Bash más útiles
• Hoja de trucos de LaTeX
• Temas más populares para Hugo
• https://www.markdownguide.org/extended-syntax/
• https://docs.readme.com/rdmd/docs/code-blocks