Validar

O blume validate verifica cada link do seu conteúdo — páginas, âncoras, assets e, opcionalmente, URLs externas — e faz o CI falhar quando algum está quebrado.

O blume validate lê seu conteúdo do mesmo jeito que um build faz e verifica cada link que encontra. Ele não gera nem compila nada, então é a verificação rápida para colocar antes do blume build:

blume validate

• Links internos de página (/guides/intro, ./sibling) precisam levar a uma página real, e os quebrados são reportados como erros. Todas as formas de link que o Markdown e o MDX renderizam são lidas: links inline, inclusive um cujo texto quebra para a linha seguinte; links no estilo de referência, verificados na definição [label]: /target (a primeira, quando um label é definido duas vezes, já que é ela que é renderizada); autolinks (<https://…>, em .md); e um href em string de um componente (<Card href="./install">). Um link relativo à raiz para um arquivo Markdown do seu conteúdo (/guides/setup.md) é verificado na página que esse arquivo publica, que é para onde o build o aponta. Se não houver nenhum arquivo com esse nome ali, ele é verificado como a cópia em Markdown da página. O destino de um link é lido do mesmo jeito que o renderizador o lê, então [x](<https://example.com/a(b>) aponta para https://example.com/a(b e ![](image\(1\).png) para image(1).png, aceitando espaços ao redor e, depois do destino, um título entre qualquer um dos delimitadores possíveis ("…", '…' ou (…)). Links em código (em blocos delimitados, inclusive um bloco dentro de uma citação, ou inline) e em comentários (<!-- … --> em .md, {/* … */} em .mdx) nunca são renderizados, então não são verificados. Um <a href> HTML em minúsculas para uma página vai para o site exatamente como foi escrito, então ele é verificado do jeito que um navegador o lê: um caminho relativo é resolvido a partir da URL da página, e nenhum basePath é adicionado (um caminho relativo à raiz ganha a base do deploy, como acontece com todo link). Uma expressão href={…} não é verificada.
• Links de âncora (#section, /guides/intro#setup) precisam corresponder a uma âncora na página de destino, que pode ser o id de um heading (gerado ou fixado), o atributo id de um elemento HTML bruto ou um <a name>. As âncoras não encontradas são reportadas como avisos. Ids dentro de blocos de código, código inline, comentários HTML e blocos <Prompt> não contam.
• Outros esquemas de link (mailto:, tel:, o deep link vscode: de um app) não são verificados, porque não tem como saber se o navegador do leitor ou algum app instalado vai abrir esse link. Os esquemas de link do próprio ReadMe são a exceção: doc:, ref:, page:, changelog: e blog: só funcionam no ReadMe e viram links mortos em qualquer outro lugar, então cada um é reportado como aviso. Em vez disso, aponte o link para o caminho da página.
• Links de assets são verificados onde o arquivo fica. Um caminho absoluto (/logo.png) é procurado no diretório public/, e uma imagem incorporada com caminho relativo (![](./diagram.png), ou o <Card img="./cover.png"> de um card) é procurada na própria pasta da página. Um link relativo para qualquer outro arquivo ([spec](./spec.pdf), um <a href> ou o href de um componente) também é procurado na própria pasta da página, já que o Blume publica o arquivo ali junto com a página. Se não houver nenhum arquivo com esse nome ao lado da página, o link é resolvido como uma rota do site e procurado no public/. O src de um elemento de mídia (<img>, <source>, <video> ou <audio>, como HTML bruto em .md ou como elemento em .mdx) é verificado do mesmo jeito: um caminho relativo é procurado ao lado da página e, se não estiver lá, no public/, onde o navegador vai requisitá-lo. Um projeto sem a pasta public/ não publica nenhum arquivo público, então nele um caminho absoluto de asset é reportado como ausente. Um link .html (./setup.html, /guides/setup.html) também é um link de arquivo: o Blume serve as páginas nas rotas delas, nunca em URLs .html. Então, a menos que o public/ tenha esse arquivo, o link é reportado, e quando alguma página corresponde a ele, a rota dela aparece como correção.
• Destinos de redirect em redirects precisam levar a algum lugar. Um to interno exato precisa levar a uma página, a um arquivo ou a outro redirect. Já o to de um padrão precisa levar a um caminho que tenha algo servido a partir do seu início literal (/v2/ em /v2/:slug*). Um destino que não leva a lugar nenhum é um aviso, apontado no to correspondente em blume.config.ts. Um link para o from de um redirect é válido de qualquer forma. Destinos externos não são verificados.
• Links externos só são verificados com --external, que vem desativado por padrão porque precisa de acesso à rede. Um link morto é um erro: um 404 ou 410, ou um nome de host que não resolve. Qualquer outra falha é um aviso, já que o problema costuma estar mais no outro site ou na rede do que no link: qualquer outro status de erro (um 401 ou 403 de um site que bloqueia bots, um 429 de limite de taxa, uma indisponibilidade 5xx), uma conexão recusada ou interrompida, ou nenhuma resposta em 10 segundos. Para deixar de fora URLs que não dá para verificar de onde o comando roda, como um domínio de placeholder, um servidor local ou um site que bloqueia bots, passe --ignore. Uma URL solta que o GitHub-flavored Markdown transforma em link por conta própria, sem nenhuma sintaxe de link ao redor, não é lida. O blume audit --external verifica essa URL no site gerado.

O que conta como página

Os links são resolvidos considerando tudo o que o site gerado serve, não só as páginas Markdown. Isso inclui páginas .astro personalizadas, as páginas da referência de API, o índice do changelog gerado e cada redirect configurado. Em um site multilíngue, também inclui a URL de fallback de uma página não traduzida em cada locale. Os arquivos que o Blume gera ao lado das suas páginas também contam, desde que estejam ativados na configuração: /llms.txt e /llms-full.txt, o sitemap, /robots.txt, os feeds RSS, /openapi.json, /agent-readability.json, /skill.md e os arquivos de descoberta em .well-known, como /.well-known/agent-skills/index.json. O mesmo vale para uma pasta em public/ com um index.html, que fica disponível em /demo ou /demo/ no caso de public/demo/index.html, do jeito que um host estático a serve. Uma página que falha ao carregar, com front matter inválido ou um .mdx que falha no parse (BLUME_MDX_SYNTAX), é reportada junto com os problemas de links. Uma página que nunca carrega é um ponto cego da validação de links, então ela não pode passar como resultado limpo.

Flags

• --external — também verifica links http(s) externos pela rede.
• --ignore <glob> — com --external, não faz a requisição de um link externo cuja URL corresponda ao glob e não reporta nada sobre ele. O glob é comparado com a URL completa do link, incluindo o esquema. O * corresponde dentro de um segmento do caminho e o ** atravessa segmentos. Assim, --ignore "https://api.acme.example/**" pula todos os links para esse host, e --ignore "http://localhost:*/**" pula todos os servidores locais. Repita a flag para adicionar mais padrões e coloque cada um entre aspas para que o seu shell não o expanda. Links internos são sempre verificados, porque são resolvidos a partir das suas próprias páginas. Então corrija o link quebrado ou adicione um redirect.
• --strict — também sai com código diferente de zero quando há avisos. As notas de nível info continuam sendo só informativas.
• --json — emite os diagnósticos como JSON no stdout em vez do relatório no terminal.

Diagnósticos

O código de saída é o contrato: erros fazem o comando sair com código diferente de zero, e o --strict faz o mesmo com os avisos.

Saída JSON

Com --json, o blume validate (e o blume doctor) escreve um objeto no stdout. Esse objeto tem uma lista diagnostics e um summary com as contagens por severidade. Cada entrada da lista traz code, severity e message, o file relativo à raiz do projeto, com line e column quando o problema tem uma localização, uma suggestion e um docsUrl apontando para a página que explica o código. O código de saída não muda. Assim, o mesmo comando pode servir de verificação no CI e alimentar uma integração com o editor.