Convenções de Markdown

Referência canônica para a forma e a formatação de Markdown em todo artefato .md e .mdx redigido. O resumo da seção Conventions do CLAUDE.md é a declaração em linha; esta página é a referência independente que os contribuidores a jusante citam.

---

1. SaborCopy Anchor Link

O GitHub-Flavored Markdown (GFM) é o sabor do host. Todo artefato é renderizado corretamente na interface web do GitHub, no site de documentação Fumadocs e em editores padrão compatíveis com Markdown.

2. Hierarquia de títulosCopy Anchor Link

Um H1 por arquivo. Os títulos seguintes descem de forma monotônica (H2 → H3 → H4), sem pular níveis. Títulos com maiúscula apenas no início da frase; nada de TUDO EM MAIÚSCULAS, nada de Maiúscula Em Todas As Palavras. O H1 carrega o título principal do documento. Em uma página do site de documentação, o title do frontmatter é renderizado como o H1 e é a âncora da página na navegação do site de documentação; por isso, o corpo da página começa no H2.

3. Blocos de códigoCopy Anchor Link

Os blocos de código cercados declaram a sua linguagem (```python, ```bash, ```yaml, ```json, ```mermaid). Blocos sem tag suprimem o realce de sintaxe e sinalizam desvio na redação; a regra MD040 do markdownlint, configurada em .markdownlint.json, impõe a tag de linguagem.

4. Links internosCopy Anchor Link

As referências cruzadas internas usam caminhos a partir da raiz do site (por exemplo, [Authorship header](/docs/reference/authorship-header)). Caminhos simples relativos ao repositório, com extensão .md/.mdx (/docs/foo.md), e URLs completas para o mesmo repositório (https://github.com/ahmed-g-gad/apothem/blob/main/...) são evitados em links dentro do site, porque dificultam renomeações de páginas e reorganizações de seções.

Esses caminhos /docs/... a partir da raiz do site — e a forma /<locale>/docs/... para os locales não padrão do cohort — são resolvidos pelo validador link-check contra o conjunto de páginas em disco sob site/content/docs/: /docs/a/b corresponde a site/content/docs/a/b.mdx ou ao índice de pasta site/content/docs/a/b/index.mdx, e a forma com locale corresponde à subárvore site/content/docs/<locale>/. Um link para uma rota removida ou renomeada não resolve para nenhum dos dois arquivos e é reportado como rota morta (um 404 visível ao usuário) pelo link-check, um matcher consultivo que não faz a execução falhar (veja a §6).

Links externos para refs mutáveis (main, master, latest, HEAD) são fixados em SHAs de commit ou em tags de lançamento sempre que a estabilidade do conteúdo vinculado importa; as referências voláteis são documentadas como tais com um comentário {/* volatile */} adjacente.

5. Cabeçalho de autoriaCopy Anchor Link

Todo artefato Markdown (com as exceções enumeradas em src/apothem/schemas/header-exceptions.txt) carrega o cabeçalho de autoria canônico, a linha única SPDX-License-Identifier: MIT, na variante de comentário do seu tipo de arquivo, conforme Cabeçalho de autoria: um comentário HTML nos arquivos .md e um comentário {/* ... */} nos arquivos .mdx. Sem frontmatter, a linha do cabeçalho é a linha 1. Com frontmatter YAML, o frontmatter permanece no byte 0 e a linha do cabeçalho vem depois do --- de fechamento.

6. ValidadoresCopy Anchor Link

O hook markdownlint de pre-commit em .pre-commit-config.yaml executa o markdownlint-cli com a política de regras de .markdownlint.json e impõe a maior parte das regras das §§1–4. O fluxo de trabalho Markdown Lint executa o mesmo hook na CI a cada push para main e a cada pull request que altere arquivos Markdown, então a CI verifica com a versão fixada pelo hook. A política desativa MD013 (comprimento de linha), MD033 (HTML em linha) e MD041 (título na primeira linha). Ela também desativa MD038, porque o sufixo canônico de rótulo de opção (Recommended) mantém o seu espaço inicial dentro de um trecho de código, e MD060, porque nenhum estilo de coluna de tabela aceita as tabelas de células compactas com uma linha delimitadora |---| justa que o corpus usa. A MD024 verifica apenas títulos irmãos, de modo que os títulos Added, Changed, Fixed e Security que cada lançamento repete em CHANGELOG.md passam. Os motivos de cada escolha ficam ao lado do hook. O hook ignora as árvores de fixtures de teste tests/fixtures/, tests/conformity/, tests/conformity-scenarios/fixtures/ e tests/scripts/inject-header/fixtures/, cujos bytes são definidos pelos testes. Ele também ignora plugins/claude-code/, que python scripts/dev/assemble_plugin_tree.py gera a partir de src/apothem/: cada passo numerado de um comando se torna um arquivo próprio, de modo que a lista de um arquivo de passo começa no número do seu passo. As fontes em src/apothem/ são verificadas; por isso, um achado no conteúdo do plugin é corrigido ali e a árvore do plugin é gerada novamente.

O file-header-grep em src/apothem/conformity/file_header_grep.py verifica a §5. O validador link-check em src/apothem/conformity/link_check.py verifica a disciplina de resolução de links da §4 — ele resolve links relativos contra o diretório do arquivo de origem e as rotas do site /docs/... (e /<locale>/docs/...) contra o conjunto de páginas de site/content/docs/, sinalizando qualquer uma que não resolva para nenhuma página em disco. Ambos são matchers consultivos executados a cada Write. Eles são executados no hook de pre-commit conformity-corpus-perwrite e no job corpus-perwrite-gate do fluxo de trabalho Conformity em .github/workflows/conformity.yml, e nos dois lugares reportam achados sem fazer a execução falhar. O python -m apothem.conformity.gate --all . --strict do job de qualidade da CI em .github/workflows/ci.yml cobre apenas os validadores independentes, portanto não executa nenhum dos dois.