IDs de títulos

IDs de títulos são uma extensão do Markdown que permite adicionar identificadores personalizados aos títulos, facilitando a criação de ligações precisas e o controlo da estrutura do documento.

Sintaxe básica

Adicionar um ID ao título

Utiliza‑se a sintaxe com chavetas imediatamente após o texto do título:

## O meu título {#custom-id}

Resultado (HTML): o ID personalizado é adicionado ao elemento do título:

<h2 id="custom-id">O meu título</h2>

IDs em vários níveis

Qualquer nível de título pode receber um ID personalizado:

# Título de nível 1 {#first-level}

## Título de nível 2 {#second-level}

### Título de nível 3 {#third-level}

#### Título de nível 4 {#fourth-level}

Cenários de uso

Criar âncoras internas

Com IDs personalizados, podes criar ligações para secções específicas do documento:

[Ir para o meu título](#custom-id)

...outro conteúdo...

## O meu título {#custom-id}

Ao clicar, a navegação salta diretamente para o título com custom-id.

Ligar a uma secção específica a partir do exterior

IDs personalizados também facilitam ligações vindas de outros documentos:

[Ligar a uma secção noutro documento](other-doc.html#specific-section)

Partilha por URL de uma secção

Um título com ID pode ser partilhado via URL apontando para a secção específica:

https://www.markdownlang.com/documentation.html#installation-guide

Utilização avançada

IDs para títulos com várias palavras

Para títulos com várias palavras, usa hífen como separador:

## Guia de instalação e configuração {#installation-and-configuration}

TOC (sumário) e IDs

Muitos processadores geram IDs automaticamente a partir do texto do título. Ao definir IDs explícitos, garantes que as ligações de TOC não se partem quando o texto do título muda:

## Introdução {#getting-started}

Mesmo que o título mude, a ligação continua válida pois o ID permanece.

Internacionalização e caracteres não latinos

Para títulos não ingleses, um ID em inglês estável é especialmente útil:

## Instruções de instalação {#installation}

## Como usar {#usage}

## Perguntas frequentes {#faq}

Compatibilidade e diferenças de implementação

Suporte por plataforma

Plataforma/Ferramenta	Suporte a ID de título	Sintaxe
GitHub Markdown	✅	{#id}
GitLab Markdown	✅	{#id}
Jekyll (kramdown)	✅	{:#id} ou {#id}
Hugo	✅	{#id}
CommonMark	❌	Sem suporte
VitePress	✅	{#id}
Pandoc	✅	{#id}

Regras de geração automática

Quando não há ID explícito, a maioria dos processadores gera um ID a partir do título:

1. Converter para minúsculas
2. Remover/substituir caracteres especiais
3. Trocar espaços por hífens
4. Remover hífens duplicados
5. Garantir unicidade (por vezes com sufixo numérico)

Exemplos:

Título	ID gerado
## Getting Started	#getting-started
## FAQ & Help	#faq-help
## 快速入门	#快速入门 ou #section-1 (varia por plataforma)

Boas práticas

Convenções de nomenclatura

✅ Recomendações:

1. **IDs curtos e descritivos**:
   - `{#installation}`
   - `{#api-reference}`
   - `{#troubleshooting}`

2. **Estilo consistente**:
   - Tudo em minúsculas
   - Hífens entre palavras
   - Evitar underscore e camelCase

3. **Estabilidade**:
   - Evitar mudar IDs com frequência
   - Manter o ID ao alterar o texto do título

❌ Evitar:

1. Caracteres especiais (por ex. `!@#$%^&*()`)
2. IDs não descritivos (por ex. `{#section1}`)
3. IDs demasiado longos
4. Espaços ou pontuação

Estrutura do documento e IDs

Em documentos grandes, padroniza IDs das secções principais para facilitar a navegação:

# Documentação do produto {#product-docs}

## Introdução {#introduction}

## Instalação {#installation}

### Instalação no Windows {#installation-windows}

### Instalação no macOS {#installation-macos}

### Instalação no Linux {#installation-linux}

## Configuração {#configuration}

## Referência de API {#api-reference}

## FAQ {#faq}

Exemplos práticos

IDs em documentação técnica

IDs de títulos ajudam o leitor a aceder diretamente a secções específicas:

# Documentação da API {#api-documentation}

## Autenticação {#authentication}

### Obter chave de API {#get-api-key}

### Autenticação OAuth {#oauth}

## Endpoints {#endpoints}

### Endpoints de utilizadores {#endpoints-users}

### Endpoints de produtos {#endpoints-products}

IDs em artigos académicos

Use IDs para citações e referências cruzadas:

# Metodologia {#methodology}

Como mostrado em [Resultados](#results), o método teve bom desempenho.

...

# Resultados {#results}

Esta secção apresenta os resultados descritos em [Metodologia](#methodology).

Resolução de problemas

ID de título não funciona

Se o ID não surtir efeito:

1. Verifica se a plataforma suporta IDs personalizados
2. Confirma a sintaxe ({#id} na maioria dos casos)
3. Garante que não há caracteres inválidos
4. Testa com outro processador de Markdown

Conflitos de ID

IDs duplicados no mesmo documento tornam as ligações imprevisíveis:

## Problema {#issue} <!-- primeiro ID -->

...

## Perguntas frequentes {#issue} <!-- ID duplicado, pode causar problemas -->

Soluções para evitar conflitos:

## Problema {#issue-description}

...

## Perguntas frequentes {#common-issues}

Espaços e caracteres especiais

Alguns processadores tratam espaços e caracteres especiais em IDs de forma inconsistente:

<!-- Pode falhar em algumas plataformas -->
## Definições avançadas {#advanced settings}

<!-- Opção mais segura -->
## Definições avançadas {#advanced-settings}

Sintaxe relacionada

• Ligações — sintaxe básica de links
• Índice — geração automática de TOC
• Notas de rodapé — referências e anotações

Ferramentas e plugins

Geração automática de TOC

Ferramentas que geram TOC a partir de títulos e IDs:

[[toc]]

# Capítulo 1 {#chapter-1}

## 1.1 Secção {#section-1-1}

# Capítulo 2 {#chapter-2}

Verificadores de IDs

• markdownlint: configurável para validar consistência de IDs
• remark-lint: regras para verificar/corrigir IDs
• markdown-toc: gera TOC com ligações automaticamente

---

IDs de títulos melhoram a usabilidade e acessibilidade de documentos Markdown. Com IDs padronizados, crias uma estrutura de ligações estável, facilitando a navegação e a referência, deixando o conteúdo mais profissional e fácil de usar.