Cómo crear bloques de código con Markdown

Mostrar código fuente de forma legible es una de las funcionalidades más potentes de Markdown. Ya sea para compartir fragmentos de programación, comandos de terminal o archivos de configuración, Markdown te ofrece varias formas de insertar código en tus documentos.

Código en línea

Para insertar código dentro de una frase, encierra el texto entre acentos graves `. Esto es útil cuando mencionas nombres de funciones, variables, comandos o etiquetas dentro de un párrafo de texto normal.

En el siguiente ejemplo insertamos código en línea:

Usa el comando `git status` para ver el estado del repositorio.

El código Markdown anterior debería renderizarse así:

Si necesitas mostrar acentos graves dentro de un código en línea, usa dobles acentos graves para delimitarlo:

``Usa `acentos graves` dentro del código.``

El código Markdown anterior debería renderizarse así:

Bloques de código con indentación

Puedes crear un bloque de código indentando cada línea con cuatro espacios o un tabulador. Esto forma parte de la sintaxis básica de Markdown y es compatible con prácticamente todos los editores.

    const saludo = "Hola";
    console.log(saludo);

El texto indentado se renderizará como un bloque de código sin formato. Sin embargo, este método no permite indicar el lenguaje de programación, por lo que no tendrás resaltado de sintaxis. Por esta razón, se recomienda usar la sintaxis de triple acento grave que veremos a continuación.

Bloques de código con triple acento grave

La forma más habitual y recomendada es usar tres acentos graves ``` antes y después del bloque de código. Esta sintaxis forma parte de la sintaxis extendida y es soportada por la gran mayoría de editores y plataformas.

Además, puedes indicar el lenguaje justo después de los acentos de apertura para activar el resaltado de sintaxis:

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

Si el editor que usas soporta el resaltado de sintaxis, el código se mostrará con colores según el lenguaje indicado. A continuación veremos ejemplos con varios lenguajes.

Ejemplo con Python

```python
def factorial(n):
    if n <= 1:
        return 1
    return n * factorial(n - 1)

print(factorial(5))  # 120
```

Ejemplo con HTML

```html
<nav>
  <ul>
    <li><a href="/">Inicio</a></li>
    <li><a href="/about">Acerca de</a></li>
  </ul>
</nav>
```

Ejemplo con CSS

```css
.container {
  display: flex;
  justify-content: center;
  align-items: center;
  min-height: 100vh;
}
```

Ejemplo con Bash

```bash
# Clonar un repositorio e instalar dependencias
git clone https://github.com/usuario/proyecto.git
cd proyecto
npm install
```

Ejemplo con JSON

```json
{
  "nombre": "Tutorial Markdown",
  "version": "1.0.0",
  "descripcion": "Guía completa de Markdown"
}
```

Bloques de código con virgulillas

Como alternativa a los acentos graves, puedes usar tres virgulillas ~~~ para crear bloques de código. El resultado es idéntico:

~~~javascript
const numeros = [1, 2, 3, 4, 5];
const dobles = numeros.map(n => n * 2);
console.log(dobles); // [2, 4, 6, 8, 10]
~~~

Esta sintaxis es menos común, pero puede ser útil cuando necesitas incluir acentos graves dentro del propio bloque de código.

Bloques de código con diff

Algunos editores y plataformas como GitHub soportan el lenguaje diff, que te permite mostrar líneas añadidas y eliminadas de forma visual. Las líneas que empiezan con + se muestran en verde y las que empiezan con - en rojo:

```diff
- const saludo = "Hola mundo";
+ const saludo = "Hola, mundo!";

- console.log(saludo)
+ console.log(saludo);
```

Este formato es especialmente útil para mostrar cambios en el código, comparar versiones o explicar correcciones en tutoriales.

Cómo indicar el nombre del archivo

Markdown no tiene una sintaxis oficial para mostrar el nombre del archivo encima de un bloque de código. Sin embargo, una convención habitual consiste en añadir un comentario o un texto en negrita justo antes del bloque:

**index.js**

```javascript
const express = require('express');
const app = express();
app.listen(3000);
```

Si trabajas con plataformas como GitHub o herramientas de documentación como Docusaurus o MkDocs, es posible que dispongan de extensiones propias para mostrar el nombre del archivo como parte del bloque de código.

Bloques de código anidados

Si necesitas mostrar un bloque de código dentro de otro bloque de código (por ejemplo, para documentar la propia sintaxis de Markdown), puedes usar un número diferente de acentos graves. Usa cuatro acentos graves `````para el bloque externo y tres `` `` para el interno:

````md
```javascript
console.log("Hola");
```
````

De este modo, los acentos graves internos no cerrarán el bloque externo.

Lenguajes soportados

La lista de lenguajes soportados depende del editor o la plataforma que estés usando, pero los más comunes incluyen:

• Web: html, css, javascript, typescript, json, xml
• Backend: python, java, php, ruby, go, rust, c, cpp, csharp
• Shell: bash, shell, powershell
• Datos: sql, graphql, yaml, toml
• Otros: markdown, diff, plaintext

Si no estás seguro del identificador exacto de un lenguaje, prueba con el nombre en minúsculas. La mayoría de procesadores Markdown utilizan bibliotecas como Prism o Highlight.js, que soportan cientos de lenguajes.

Esto ha sido todo. Espero que te haya resultado útil.