Como gerar um índice Markdown (âncoras compatíveis com GitHub)

A primeira vez que um README meu cruzou mil linhas, EU fiz o que todo mundo faz: EU rolei Então EU rolei mais um pouco Em algum lugar ao redor da quarta passagem procurando o & quot; Deployment" seção, EU desisti e comecei a escrever à mão um índice na parte superior do arquivo Isso funcionou até que EU renomeei um título, esqueci de atualizar o link e enviei um README onde o & quot; Configuration" apontou para nada Um link quebrado na página em sua própria documentação é uma coisa pequena, mas é o tipo de coisa pequena que diz a um leitor que ninguém está cuidando da loja.

Eu construo [Toolz.dev] (/, uma coleção de utilitários de desenvolvedor baseados em navegador, e mantenho muito Markdown: guias de ferramentas, arquivos README, especificações internas e os documentos que você está lendo agora Um índice que EU tenho que manter à mão é um índice que acabará por mentir Então EU construí o Gerador TOC Markdown para fazer a parte chata corretamente todas as vezes, e este guia é tudo o que aprendi sobre os links de âncora durante a construção.

tl;dr: Um índice Markdown é uma lista aninhada de links que saltam para títulos na mesma página Os links funcionam porque cada título recebe um id de âncora automático, e o slug que o GitHub atribui segue uma regra específica: minúsculas o texto, soltar pontuação diferente de hífens e transformar espaços em hífens Cole seu Markdown no gerador, escolha quais níveis de cabeçalho incluir e copie a lista A ferramenta calcula as renderizações exatas do slugs GitHub, incluindo o -1 sufixo para títulos duplicados, então nada quebra quando você o cola de volta.

O que é um índice Markdown?

Um índice no Markdown não é uma sintaxe especial. ponto comum define tal construção, e nem o GitHub Flavored Markdown É uma lista comum onde cada item é um link, e cada link aponta para uma âncora dentro do mesmo documento Quando um renderizador Markdown como o GitHub transforma um cabeçalho em HTML, ele também dá esse cabeçalho a id atributo. Um título escrito como ## Getting Started torna-se aproximadamente <h2 id="getting-started">Getting Started</h2>. Uma vez que esse id exista, um link escrito como [Getting Started](#getting-started) rola a página até ele.

Portanto, um índice é apenas uma coleção desses links, recuados para espelhar a hierarquia de cabeçalho:

- [Getting Started](#getting-started)
  - [Installation](#installation)
  - [Configuration](#configuration)
- [Usage](#usage)

Todo o truque vive em uma palavra a partir desse exemplo: a âncora Erre a âncora e o link falha silenciosamente, rolando para lugar nenhum Acerte e o bloco de conteúdo funciona no GitHub, na maioria dos geradores de sites estáticos e dentro de plataformas de documentação que seguem a mesma convenção A parte difícil não é escrever a lista A parte difícil é prever o id exato que cada renderizador atribuirá, e é por isso que fazê-lo manualmente é um jogo perdedor em qualquer documento que mude.

Como as âncoras de rumo são realmente geradas?

GitHub' s slug algoritmo é determinístico e vale a pena memorizar, porque uma vez que você sabe que você pode prever cada âncora na página Os passos, em ordem, são: converter o texto do título para minúsculas, remover qualquer caractere que não é uma letra, um número, um espaço, ou um hífen, e, em seguida, substituir cada espaço por um hífen Essa é a regra inteira.

As consequências são onde as pessoas tropeçam Considere um título como ## Set Up & Config. A caixa inferior dá set up & config. Remover o e comercial (mas deixar os espaços ao seu redor) dá set up config com dois espaços onde o & costumava ser. Transformar espaços em hífens produz set-up--config, com um hífen duplo Esse hífen duplo parece um erro, mas é exactamente o que o GitHub renderiza, por isso é exactamente o que o seu link precisa Uma ferramenta que o & quot; limpa o & quot; o hífen duplo produziria uma ligação que não resolve.

Os títulos com muita pontuação entram em colapso mais longe do que você espera. ## C++ Guide torna-se c-guide, porque ambos os sinais de mais são despojados e o espaço restante se torna um único hífen. ## What's New? torna-se whats-new0, porque o apóstrofo e o ponto de interrogação desaparecem Emoji e a maioria dos símbolos desaparecem inteiramente O Gerador TOC Markdown aplica este caractere de regra para o caractere, então o slug mostra que você é o id que o GitHub irá construir, sem nenhuma suposição envolvida.

O que acontece quando dois títulos são iguais?

Os documentos repetem títulos. Um changelog pode ter três seções, todas intituladas ### Fixed. Se cada um deles produziu o slug fixed, só funcionaria o primeiro link O GitHub resolve isso numerando as duplicatas: a primeira Fixed obter fixed, o segundo fica fixed-1, o terceiro fica fixed-2, e assim por diante na ordem do documento O sufixo é anexado após a base slug com um hífen.

Esta é uma das razões mais comuns de um índice escrito à mão sair de sincronia Você adiciona uma segunda seção com um nome que você já usou, a âncora silenciosamente se torna -1, e seu link antigo agora aponta para o lugar errado ou para nenhum lugar O gerador rastreia cada slug que emitiu e aplica o mesmo sufixo numérico, portanto, títulos repetidos vinculam-se à ocorrência certa.

Que tipos de títulos a ferramenta lê?

Markdown tem dois estilos de cabeçalho, e um gerador completo tem que ler ambos O comum é ATX, onde uma linha começa com um a seis # caracteres seguidos pelo texto do título A contagem de hashes é o nível, então # é um H1 e ###### é um H6. o segundo estilo é Setext, onde uma linha de texto é sublinhada na próxima linha com sinais iguais para um H1 ou hífens para um H2:

Document Title
==============

A Section
---------

Ambos os estilos produzem títulos com ids âncora, então ambos pertencem a um índice A parte complicada com Setext está dizendo um título real sublinhado à parte de uma regra horizontal, porque uma linha de hífens pode significar qualquer uma das duas A regra que o gerador usa é que um sublinhado de hífen só conta como um título quando a linha diretamente acima dela é texto de parágrafo comum, não uma linha em branco, um item de lista, um blockquote ou outra construção de bloco A --- sentar-se sozinho com linhas em branco ao redor é uma ruptura temática e é corretamente ignorado.

Há mais uma categoria para tratar, e é aquela que silenciosamente arruína ferramentas ingênuas: cabeçalhos dentro do código Se o seu documento contém um bloco de código cercado que mostra comandos shell, algumas dessas linhas começarão com # como comentários. Aqueles não são títulos, e eles nunca devem aparecer no conteúdo O gerador rastreia blocos de código cercados (os delimitados por backticks triplos ou til triplos) e pula qualquer # linha dentro deles Um comentário shell como # install dependencies em um exemplo fica onde pertence, no exemplo.

Como faço para controlar a profundidade do índice?

Um índice que lista cada título até H6 não é um índice, é uma segunda cópia do documento A maioria dos READMEs lê melhor quando o conteúdo cobre apenas H2 e H3, dando aos leitores as seções principais e seus filhos imediatos sem afogá-los em detalhes O gerador permite definir um nível mínimo e um máximo, e inclui apenas os títulos que se enquadram nesse intervalo.

O comportamento sutil aqui é o recuo Se você incluir H2 a H4, o rumo mais raso que você manteve é um H2, e ele deve ficar nivelado contra a margem esquerda em vez de recortado como se um H1 invisível estivesse acima dele O gerador mede a profundidade de aninhamento em relação ao rumo mais raso que realmente inclui, então um bloco de conteúdo que começa em H2 começa sem recuo Esta é a diferença entre uma lista que parece intencional e uma que parece ter perdido sua primeira coluna.

Você também começa a escolher o marcador de lista Uma lista não ordenada usa um marcador para cada entrada, que é o visual convencional para um README Uma lista ordenada numera as entradas, e o gerador reinicia a contagem dentro de cada nível de aninhamento para que um contorno numerado leia corretamente em vez de contar direto de um a cinquenta A indentação pode ser dois espaços, quatro espaços ou uma guia, dependendo do que o resto do seu documento usa.

E quanto aos títulos acentuados e não latinos?

Nem todo título é inglês simples, e a regra slug tem que lidar com isso O GitHub mantém letras de outros alfabetos em vez de retirá-las, então um título como ## Configuración mantém seus caracteres acentuados e se torna configuración, e um cabeçalho em cirílico ou grego mantém essas letras também O que é removido é pontuação e símbolos, não letras, independentemente do script O gerador segue o mesmo princípio, tratando qualquer letra ou dígito Unicode como um caractere slug válido, de modo que um documento multilíngue produz âncoras que correspondem ao que o GitHub renderiza, em vez de uma linha de links vazios.

Isso importa mais do que parece à primeira vista Equipes que escrevem documentação em espanhol, alemão ou japonês muitas vezes acham que as ferramentas ingênuas slug mangle seus cabeçalhos em âncoras inutilizáveis, porque essas ferramentas assumem ASCII Se seus links já apontaram para nada em um README traduzido, um slug que silenciosamente descartou as letras não-ASCII é quase certamente o porquê Gerar o bloco de conteúdo com uma ferramenta com reconhecimento Unicode remove toda essa classe de link quebrado, e isso significa que o mesmo documento pode conter cabeçalhos em mais de um idioma sem que nenhum deles perca suas âncoras.

Quando devo usar um TOC gerado versus um automático?

Algumas plataformas constroem um índice para você O GitLab suporta um [[_TOC_]] token, algumas wikis injetam uma caixa de conteúdo automaticamente, e estruturas de documentação como o Docusaurus renderizam um esboço na página de seus títulos sem que você escreva nada Quando você estiver trabalhando dentro de um desses sistemas, use o recurso integrado Ele permanece atual com esforço zero porque a plataforma o regenera em cada renderização.

O gerador ganha o seu lugar em qualquer outro lado, e o & quot; em todo o lado" é um lugar grande Os READMEs do GitHub não geram automaticamente um bloco de conteúdo, portanto, uma página de destino do repositório precisa de uma lista real de Markdown comprometida no arquivo O Markdown que é convertido em outra coisa, enviado por e-mail, colado em um problema ou renderizado por um visualizador mínimo precisa de um bloco de conteúdo estático porque não há mecanismo para construir um em tempo real A tabela abaixo estabelece onde cada abordagem se encaixa.

situação	Melhor abordagem	por que
GitHub README	Lista estática gerada	O GitHub renderiza ids de título, mas não insere automaticamente um TOC
Wiki ou documentos do GitLab	[[_TOC_]] token	Nativo, sempre atual
Docusaurus/página MkDocs	Esboço embutido	A estrutura o traduz de títulos
Arquivo de Markdown simples para exportação	Lista estática gerada	Nenhum renderizador para construir um no momento da visualização
Descrição do pedido de emissão ou retirada	Lista estática gerada	As âncoras funcionam, mas nada gera automaticamente a lista

A regra prática: se a coisa que exibe seu Markdown pode construir o conteúdo em si, deixe-o Se o seu Markdown pode ser lido em algum lugar que não pode, gere a lista e comprometa-o Quando você estiver convertendo entre formatos, o Conversor de marcação para HTML e o Conversor HTML para Markdown combine naturalmente com um bloco de conteúdo gerado, pois as âncoras sobrevivem à viagem de ida e volta.

Como isso se encaixa no resto de um fluxo de trabalho Markdown?

Um índice é uma peça de manter documentos longos legíveis, e funciona melhor ao lado de alguns hábitos Mantenha o texto do seu título estável depois de publicar links para ele, porque renomear um título muda seu slug e quebra todos os links que apontavam para ele Quando você renomear, regenere o conteúdo em vez de editar o link que você lembra, já que uma renomeação geralmente desloca a numeração de sufixo duplicado mais abaixo no arquivo.

O conteúdo estruturado se beneficia de outras ferramentas da mesma família Quando um documento se apoia em dados tabulares, o Gerador de mesa de remarcação constrói tabelas de pipe corretamente alinhadas que uma tabela digitada à mão quase nunca acerta Quando você herda HTML confuso que precisa se tornar Markdown limpo, ou Markdown limpo que precisa se tornar HTML, os conversores lidam com a tradução preservando a estrutura de cabeçalho E se você estiver auditando um documento para o comprimento ou o equilíbrio de palavras-chave, o contador de palavras fornece os números sem colar seu rascunho em nada baseado na nuvem.

Tudo é executado no navegador, o que importa mais do que parece Um README geralmente contém nomes de recursos inéditos, URLs internos ou detalhes do cliente, e nada disso deve ser carregado em um servidor de terceiros apenas para construir uma lista de links O gerador analisa seu Markdown com JavaScript do lado do cliente, para que o documento nunca saia da sua máquina Se a privacidade no ferramental do desenvolvedor for algo em que você pensa, o write-up on Privacidade de dados e ferramentas online cobre por que o processamento local é o padrão certo e o Kit de ferramentas para desenvolvedores web arredonda o resto dos utilitários que alcanço diariamente.

Um exemplo rápido

Suponha que você tenha este documento:

# Payment Service

## Getting Started

### Requirements

### Local Setup

## API Reference

### Authentication

### Errors

## Deployment

Defina o intervalo de H2 a H3, escolha uma lista com marcadores e deixe os links de ancoragem ligados O gerador produz:

- [Getting Started](#getting-started)
  - [Requirements](#requirements)
  - [Local Setup](#local-setup)
- [API Reference](#api-reference)
  - [Authentication](#authentication)
  - [Errors](#errors)
- [Deployment](#deployment)

O título H1 é excluído porque fica acima do intervalo, as seções H2 ficam niveladas à esquerda e seus filhos H3 ficam recuados em um nível Cole esse bloco logo abaixo do título em seu README e cada entrada salta para sua seção no GitHub. Esse é o trabalho completo, feito no tempo que leva para ler esta frase, e permanece correto porque uma máquina calculou o slugs em vez de você.

Perguntas frequentes

Como funciona um índice Markdown?

Um índice Markdown é uma lista de links que apontam para âncoras de cabeçalho dentro da mesma página Cada cabeçalho em um documento Markdown recebe um id automático e um link escrito como Seção salta para ele Esta ferramenta lê seus títulos, constrói as âncoras correspondentes e monta a lista aninhada para você.

Como são gerados os links âncora?

As âncoras seguem a regra GitHub slug: o texto do título é minúsculo, a pontuação diferente dos hífens é removida e os espaços tornam-se hífens. " Configurar & amp; Configurar & quot; torna-se o id set-up-config. Quando dois títulos produzem o mesmo slug, o segundo recebe um sufixo -1, o terceiro -2 e assim por diante, combinando como o GitHub os renderiza.

Funciona com arquivos GitHub README?

Sim. O algoritmo slug espelha aquele que o GitHub usa para renderizar IDs de título, para que os links de índice sejam resolvidos corretamente dentro de um README no github.com. Cole seu README, escolha seus níveis de cabeçalho e solte a lista gerada abaixo do título.

Posso escolher quais níveis de cabeçalho aparecem?

Sim. Defina um nível mínimo e máximo, por exemplo H2 a H4, e apenas os títulos nesse intervalo estão incluídos A profundidade de nidificação é medida em relação ao título incluído mais raso, de modo que o contorno nunca comece com um grande recuo vazio.

Os títulos dentro dos blocos de código estão incluídos?

As linhas no # dentro de um bloco de código cercado (delimitadas por backticks triplos ou til triplos) são tratadas como código, não como títulos, portanto, trechos de exemplo e comentários de shell nunca aparecem no índice.

Qual é a diferença entre um TOC ordenado e não ordenado?

Um índice não ordenado usa marcadores de marcadores, como um hífen para cada entrada, enquanto um ordenado usa números que aumentam dentro de cada nível de aninhamento Escolha ordenado quando os leitores se beneficiam de um contorno numerado e não ordenado para um bloco de conteúdo mais leve e convencional.

A ferramenta suporta títulos Setext?

Sim. lê ambos os títulos ATX que começam com títulos # e Setext, onde uma linha de texto é sublinhada com sinais iguais para H1 ou hífens para H2. Ambos os estilos são convertidos em links âncora da mesma maneira.

O gerador Markdown TOC é gratuito e privado?

Sim. é totalmente gratuito sem inscrição e sem limites Toda a análise acontece no seu navegador usando JavaScript do lado do cliente, então o Markdown que você cola nunca sai do seu dispositivo e a ferramenta continua funcionando offline depois que a página é carregada.

---