Ir para o conteúdo
Voltar ao Blog
quarta-feira, 18 de novembro de 2026

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.

Como criar um índice Markdown para um README do GitHub

Coloque 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

Copie um README completo com índice

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.

Encontre a âncora gerada para o título

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).

Corrija uma ligação que leva ao sítio errado

O que aconteceO que verificar
A ligação fica no início do ficheiroConfirme que o fragmento começa com cardinal e coincide com a âncora do título renderizado.
As duas entradas abrem a primeira secção ExamplesCopie o fragmento da segunda secção. No exemplo, termina em -1.
A ligação falhou depois de uma alteraçãoConfirme 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 principalRecue o marcador. O nível do título e o recuo da lista são definidos em separado.
Funciona numa plataforma e falha noutraCopie 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.

Partilhe a estrutura numa imagem

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

README renderizado com um índice, uma entrada recuada e duas secções Examples

Abrir o PNG original