Como fazer uma secção recolhível em Markdown:as etiquetas details e summary.

A sintaxe

Uma secção recolhível é um simples elemento HTML: <details> é o contentor, <summary> é a linha clicável e tudo o que vem depois do summary fica escondido até o leitor clicar. É o navegador (ou a vista web da aplicação Markdown) que abre e fecha, por isso não há scripts nem sintaxe extra para aprender.

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

Hidden text goes here.

</details>

Fechada, mostra um pequeno triângulo e as palavras Click to expand. Ao clicar, o triângulo roda e aparece o texto. É o mesmo padrão que os README, as issues e os comentários de pull requests do GitHub usam para registos longos e notas opcionais.

A regra da linha em branco

O Markdown dentro de um bloco <details> só é processado se estiver separado das etiquetas HTML por uma linha em branco. É assim que o CommonMark lê um bloco HTML: vai até à linha em branco seguinte e passa como HTML bruto. Sem a linha em branco, o seu **negrito** e a sua lista ficam como caracteres literais.

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

<details>
<summary>Works</summary>

- this one is a list

</details>

Ponha uma linha em branco depois de </summary> e outra antes de </details>. A própria linha do summary também é HTML, por isso use aí <b>negrito</b> ou <code>código</code>, e não Markdown.

Aberta por predefinição

Junte o atributo open para começar com a secção expandida. O leitor pode sempre recolhê-la.

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

Node 20 or later.

</details>

Use-o com moderação: numa página em que tudo começa aberto não há razão para ser recolhível, e numa em que tudo começa fechado escondem-se as partes úteis. Uma boa regra é manter a resposta visível e dobrar as provas, como um resultado longo, uma configuração completa ou uma lista de casos-limite.

Exemplos: código, aninhamento e uma lista longa

Um bloco de código dentro de uma secção precisa das suas linhas em branco como qualquer outro Markdown:

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

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

</details>

As secções podem ser aninhadas. Indente a interior se quiser, mas o que conta são as linhas em branco:

<details>
<summary>Troubleshooting</summary>

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

Check the log in the console.

</details>

</details>

Eis uma secção como o leitor a vê, fechada até clicar:

Mostrar o registo completo

Tudo o que está aqui fica escondido até clicar no título.

Quando usar uma secção recolhível

Vale a pena dobrar quando o leitor consegue concluir a tarefa sem abrir a secção. Bons candidatos são o resultado longo de um comando, um ficheiro de configuração completo, uma tabela de opções, um registo de alterações de versões antigas ou uma lista de passos para resolver problemas raros. Uma nota curta de que a maioria dos leitores precisa deve ficar à vista.

Uma secção também é uma forma arrumada de pôr registos longos colados num relatório de erro ou na descrição de uma pull request: o leitor vê primeiro o resumo do que correu mal e só abre o registo se precisar. Dê ao summary um título específico, como Registo de compilação (412 linhas), para que o leitor saiba o que está lá dentro antes de clicar.

Erros comuns

• Sem linha em branco. O texto no interior mostra Markdown em bruto. Junte uma linha em branco depois do summary e antes da etiqueta de fecho.
• Markdown no summary. Use aí etiquetas HTML.
• Falta a etiqueta de fecho. Tudo o que está abaixo fica dentro da secção.
• Uma aplicação que remove o HTML. Alguns renderizadores removem as etiquetas em que não confiam, e então o texto fica simplesmente visível. Se a secção tem de funcionar em todo o lado, teste-a onde vai ser lida.
• Títulos dentro do summary. O título não aparece no índice da maioria das aplicações. Ponha o título acima da secção.

O texto recolhido continua no ficheiro, por isso a pesquisa e os diffs veem-no, mas um leitor que nunca clique não. Não esconda nada essencial, como um aviso.

Vê-la a funcionar

Para verificar uma secção, abra o ficheiro num leitor que formate HTML. O DotMD mostra <details> como uma secção que abre ao clicar, com o Markdown no interior formatado, e no DotMD Editor Insert → Collapsible Section escreve as etiquetas por si. A leitura é gratuita.

Perguntas sobre secções recolhíveis em Markdown

Mais perguntas