Como criar um índice Markdown para um README do GitHub
Crie um índice com ligações para um README do GitHub. Copie um exemplo com subsecções, verifique títulos repetidos e corrija ligações após editar.
Nesta página
01Copie um README completo com índice02Encontre a âncora gerada para o títuloColoque uma lista com marcadores no início do README. Uma ligação como [Quick start](#quick-start) leva ao título ## Quick start. O texto entre parênteses retos aparece ao leitor. A parte a seguir ao cardinal identifica o título de destino.
O GitHub também cria um esquema com base nos títulos do ficheiro Markdown renderizado. Pode usá-lo para navegar no README de outro projeto. Se quiser que as secções principais fiquem visíveis ao abrir o seu ficheiro, escreva um índice junto ao início. Documentação do GitHub sobre ficheiros README
O exemplo tem uma entrada subordinada e dois títulos iguais. Copie o bloco para um ficheiro Markdown e experimente as quatro ligações.
# Field Notes
## Contents
- [Quick start](#quick-start)
- [Import a notebook](#import-a-notebook)
- [Examples for writers](#examples)
- [Examples for reviewers](#examples-1)
## Quick start
Open a notebook and add your first entry.
### Import a notebook
Choose an existing folder of Markdown notes.
## Examples
Writers can group entries by trip.
## Examples
Reviewers can scan entries by date.
Import a notebook fica recuado sob Quick start, tal como o título H3 fica dentro da secção H2 no texto. As duas secções Examples mantêm o mesmo nome. O índice indica a quem se destina cada uma, e os fragmentos apontam para secções diferentes.
Num título simples, o GitHub converte as letras em minúsculas, troca os espaços por hífenes e remove marcas de formatação e sinais como o ponto de interrogação. Quando a âncora se repete, acrescenta um sufixo numérico. No exemplo, os destinos são #examples e #examples-1. Regras do GitHub para ligações a secções
Se o título tiver pontuação, formatação ou caracteres fora de ASCII, abra o ficheiro renderizado no GitHub. Passe o cursor sobre o título, clique no ícone da ligação e copie o fragmento da barra de endereços. Para ligar a partir de outro ficheiro Markdown na mesma pasta, escreva primeiro o nome do ficheiro, como em [Quick start](README.md#quick-start).
| O que acontece | O que verificar |
|---|---|
| A ligação fica no início do ficheiro | Confirme que o fragmento começa com cardinal e coincide com a âncora do título renderizado. |
| As duas entradas abrem a primeira secção Examples | Copie o fragmento da segunda secção. No exemplo, termina em -1. |
| A ligação falhou depois de uma alteração | Confirme a âncora após mudar o nome ou a posição do título e atualize as referências antigas. |
| Uma entrada subordinada aparece no mesmo nível da principal | Recue o marcador. O nível do título e o recuo da lista são definidos em separado. |
| Funciona numa plataforma e falha noutra | Copie a âncora no sítio onde os leitores vão abrir o ficheiro. |
Depois de editar, abra o README renderizado e clique em cada entrada. Confirme os destinos, sobretudo quando alterar a ordem de títulos repetidos. Comece pelas secções de que os leitores precisam, como instalação, utilização e resolução de problemas. Acrescente subsecções quando ajudarem a navegar num texto longo.
O PNG foi descarregado do editor Markdown2Image com o mesmo código. Mostra a hierarquia dos títulos e a lista recuada. Num diapositivo sobre a estrutura da documentação, coloque a ligação do README junto à imagem para que os leitores possam abrir o ficheiro e saltar para uma secção. Pré-visualizar o exemplo no Markdown2Image