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.

Para crear uno, sigue estos pasos:

1. Abre el contenedor con <details> en una línea propia.
2. Escribe el título visible entre <summary> y </summary>. Es lo único que se ve con el bloque plegado, así que conviene que diga qué hay dentro: "Ver la solución" informa más que "Más".
3. Deja una línea en blanco y escribe el contenido que quieres ocultar.
4. Deja otra línea en blanco y cierra el bloque con </details>.

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.

La propia documentación de GitHub muestra este patrón con encabezados, texto, imágenes y bloques de código dentro del desplegable, siempre separados de las etiquetas por líneas en blanco.

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.

Desplegables anidados

Puedes meter un desplegable dentro de otro para crear varios niveles, por ejemplo una pregunta frecuente que a su vez contiene una explicación avanzada. Basta con escribir un bloque <details> completo dentro del contenido del primero.

En el siguiente ejemplo anidamos dos desplegables:

<details>
<summary>Instalacion</summary>

Ejecuta el instalador y sigue los pasos.

<details>
<summary>Instalacion manual (avanzado)</summary>

Descarga el paquete y copialo en la carpeta de la aplicacion.

</details>

</details>

Cada bloque interior debe cerrarse con su propio </details> antes de cerrar el exterior. Si te saltas un cierre, el resto del documento puede acabar dentro del desplegable. Con dos niveles suele bastar: a partir de ahí el lector pierde la referencia de dónde está.

Cuándo usar un desplegable

Un desplegable tiene sentido cuando el contenido es útil pero no todo el mundo lo necesita. Estos son los casos más habituales:

• Preguntas frecuentes en un README: cada pregunta en el <summary> y la respuesta dentro. El lector ve la lista completa de preguntas de un vistazo y solo abre la que le interesa. Si estás preparando uno, tienes una base en nuestra plantilla de README y en la guía para escribir un README.
• Logs y salidas largas: en una issue o en un informe de errores, la salida completa de un comando ocupa cientos de líneas. Plegada, no tapa la explicación del problema.
• Spoilers: soluciones de ejercicios, respuestas de un cuestionario o el final de una historia, para que el lector decida cuándo verlas.
• Detalles avanzados: configuraciones opcionales o explicaciones técnicas que el usuario medio puede saltarse.

Lo que no conviene es esconder información imprescindible. Si el lector necesita leerlo para seguir, déjalo visible. Para destacar un aviso importante es mejor mostrar una advertencia, y para ayudar a navegar un documento largo, una tabla de contenidos.

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, igual que los editores que permiten insertar HTML en Markdown. 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.

Cuando una plataforma filtra el HTML, el resultado varía: unas eliminan las etiquetas y muestran todo el contenido sin plegar, y otras muestran las etiquetas como texto. En ambos casos el contenido sigue ahí, pero sin el efecto desplegable. Por eso conviene comprobar siempre cómo se ve el documento en el destino final antes de publicarlo.

Si necesitas un desplegable en un entorno que no admite HTML, la alternativa más segura es un enlace ancla a otra sección del documento, de modo que el contenido secundario quede al final y no interrumpa la lectura.

Desplegables en Obsidian

En el siguiente ejemplo creamos un callout plegado por defecto:

> [!faq]- ¿Se pueden plegar los callouts?
> Si. En un callout plegable el contenido queda oculto hasta que lo despliegas.

Los callouts también se pueden anidar en varios niveles, igual que los desplegables HTML. La diferencia es que esta sintaxis es propia de Obsidian: si abres el archivo en otro editor, verás una cita normal con el texto [!faq]- al principio. Tienes todos los detalles en la documentación oficial de callouts.

Esto ha sido todo.