Cómo hacer una sección desplegable en Markdown:las etiquetas details y summary.

La sintaxis

Una sección desplegable es un elemento HTML normal: <details> es el contenedor, <summary> es la línea en la que se hace clic y todo lo que sigue al summary queda oculto hasta que el lector hace clic. El navegador (o la vista web de la app de Markdown) se encarga de abrir y cerrar, así que no hay script ni sintaxis extra que aprender.

<details>
<summary>Click to expand</summary>

Hidden text goes here.

</details>

Cerrada, el lector ve un pequeño triángulo y las palabras Click to expand. Al hacer clic, el triángulo gira y se muestra el texto. Es el mismo patrón que usan los README, los issues y los comentarios de pull request de GitHub para registros largos y notas opcionales.

La regla de la línea en blanco

El Markdown dentro de un bloque <details> solo se procesa si está separado de las etiquetas HTML por una línea en blanco. Así lee CommonMark un bloque HTML: llega hasta la siguiente línea en blanco y se pasa tal cual como HTML sin procesar. Sin la línea en blanco, tu **bold** y tu lista quedan como caracteres literales.

<details>
<summary>Broken</summary>
- this list is not turned into a list
</details>

<details>
<summary>Works</summary>

- this one is a list

</details>

Pon una línea en blanco después de </summary> y otra antes de </details>. La propia línea del summary también es HTML, así que usa ahí <b>bold</b> o <code>code</code>, no Markdown.

Abierta por defecto

Añade el atributo open para que la sección empiece desplegada. El lector todavía puede plegarla.

<details open>
<summary>Prerequisites</summary>

Node 20 or later.

</details>

Úsala con moderación: en una página donde todo empieza abierto no hay motivo para plegar, y en una donde todo empieza cerrado se esconden las partes útiles. Una buena regla es dejar visible la respuesta y plegar las pruebas, como una salida larga, una configuración completa o una lista de casos límite.

Ejemplos: código, anidación y una lista larga

Un bloque de código dentro de una sección necesita sus líneas en blanco como cualquier otro Markdown:

<details>
<summary>Full config</summary>

```json
{ "retries": 3, "timeout": 30 }
```

</details>

Las secciones se pueden anidar. Sangra la interior si quieres, pero lo que importa son las líneas en blanco:

<details>
<summary>Troubleshooting</summary>

<details>
<summary>The app does not start</summary>

Check the log in the console.

</details>

</details>

Así ve el lector una sección, cerrada hasta que se hace clic:

Show the full log

Everything here is hidden until the title is clicked.

Cuándo usar una sección desplegable

Plegar vale la pena cuando el lector puede terminar la tarea sin abrir la sección. Buenos candidatos son una salida larga de comandos, un archivo de configuración completo, una tabla de opciones, un historial de cambios de versiones antiguas o una lista de pasos de solución de problemas poco frecuentes. Una nota corta que necesita la mayoría de los lectores debe quedar a la vista.

Una sección también es una forma ordenada de poner registros largos pegados en un informe de error o en la descripción de un pull request: el lector ve primero el resumen de lo que salió mal y abre el registro solo si lo necesita. Dale al summary un título concreto, como Build log (412 lines), para que el lector sepa qué hay dentro antes de hacer clic.

Errores habituales

• Sin línea en blanco. El texto de dentro muestra Markdown sin procesar. Añade una línea en blanco después del summary y antes de la etiqueta de cierre.
• Markdown en el summary. Usa etiquetas HTML ahí.
• Falta la etiqueta de cierre. Todo lo de debajo queda dentro de la sección.
• Una app que elimina el HTML. Algunos renderizadores quitan las etiquetas en las que no confían, y entonces el texto simplemente se ve. Si la sección debe funcionar en todas partes, pruébala donde se vaya a leer.
• Encabezados dentro del summary. El encabezado no aparece en el índice de la mayoría de las apps. Pon mejor el encabezado encima de la sección.

El texto plegado sigue estando en el archivo, así que la búsqueda y los diffs lo ven, pero un lector que nunca hace clic no. No escondas nada esencial, como una advertencia.

Verlo funcionar

Para comprobar una sección, abre el archivo en un lector que renderice HTML. DotMD muestra <details> como una sección que se abre con un clic, con el Markdown de dentro formateado, y en DotMD Editor Insert → Collapsible Section escribe las etiquetas por ti. Leer es gratis.

Preguntas sobre las secciones desplegables en Markdown

Más preguntas