Cómo crear bloques desplegables con Markdown

Los bloques desplegables (también llamados acordeones o spoilers) son secciones que aparecen plegadas por defecto y que el lector despliega haciendo clic sobre un título. Son muy útiles en archivos README, en preguntas frecuentes y en cualquier documento largo donde quieras ocultar contenido secundario sin romper la lectura.

Markdown estándar no define una sintaxis propia para los desplegables, pero la mayoría de procesadores y plataformas (entre ellas GitHub, GitLab y Reddit) admiten las etiquetas HTML <details> y <summary>, que son la forma nativa de hacerlo en HTML5.

Estructura básica con details y summary

Un bloque desplegable se compone de dos partes: un contenedor <details> que envuelve todo el bloque y una etiqueta <summary> que define el texto visible cuando el bloque está plegado. Todo lo que esté fuera del <summary>, pero dentro del <details>, queda oculto hasta que el usuario hace clic.

En el siguiente ejemplo creamos un desplegable sencillo con un párrafo de texto en su interior:

<details>
<summary>Haz clic para ver más</summary>

Aquí va el contenido oculto del bloque desplegable. Puede ser texto plano, listas, imágenes o lo que necesites.

</details>

Si tu editor o plataforma soporta HTML, el resultado se verá así:

Fíjate en las líneas en blanco del ejemplo anterior, antes y después del contenido interno. Son importantes en muchos procesadores de Markdown: sin ellas, el contenido se trata como HTML plano y no se procesa la sintaxis Markdown que pongas dentro.

Desplegable abierto por defecto

Si quieres que el bloque aparezca ya desplegado al cargar la página, basta con añadir el atributo open a la etiqueta <details>. El usuario podrá plegarlo manualmente.

En el siguiente ejemplo creamos un desplegable que arranca abierto:

<details open>
<summary>Sección abierta por defecto</summary>

Este contenido se ve directamente al cargar la página, pero el usuario puede plegarlo si quiere.

</details>

El resultado se verá así:

Desplegable con Markdown dentro

Una de las grandes ventajas de este patrón es que el contenido interno admite Markdown normal, siempre que dejes una línea en blanco después del <summary> y antes del </details> de cierre. Puedes incluir listas, enlaces, bloques de código, imágenes y casi cualquier elemento.

En el siguiente ejemplo metemos una lista y un bloque de código dentro del desplegable:

<details>
<summary>Comandos útiles de Git</summary>

Algunos comandos básicos:

- `git status`: muestra el estado del repositorio
- `git add`: añade archivos al área de preparación
- `git commit`: confirma los cambios

Ejemplo de uso:

```bash
git add .
git commit -m "Primer commit"
```

</details>

El resultado renderizado en plataformas como GitHub será un bloque desplegable con la lista y el bloque de código formateados correctamente en su interior. Esta técnica es especialmente útil en archivos README, donde puedes ocultar instrucciones largas, capturas de pantalla pesadas o secciones avanzadas que no todo el mundo necesita leer.

Consideraciones de compatibilidad

No todos los procesadores de Markdown manejan las etiquetas <details> de la misma forma. GitHub, GitLab, Gitea y la mayoría de generadores de sitios estáticos modernos las soportan sin problema. Sin embargo, plataformas más restrictivas como algunos foros, wikis antiguos o gestores de contenido suelen filtrar el HTML por seguridad y eliminarán los bloques.

Si necesitas un desplegable en un entorno que no admite HTML, considera alternativas como un simple enlace ancla a otra sección del documento o, si trabajas en una herramienta concreta, revisa si dispone de una sintaxis propia como las callouts plegables de Obsidian.

Esto ha sido todo.