Jamdesk Documentation logo

Corrigir links quebrados

Saiba como o jamdesk fix repara links internos quebrados e âncoras com erros de digitação, com uma prévia antes de gravar as alterações.

jamdesk fix repara o que jamdesk broken-links relata. Ele lê os mesmos avisos e reescreve um link quando encontra um único destino correto e claro. Casos ambíguos são deixados intactos para revisão manual.

Corrigir com IA faz o mesmo reparo em um build a partir do painel. Ele também preenche descrições de páginas ausentes. Ele envia as alterações para o GitHub.

Ele corrige dois tipos de links internos quebrados:

  • Âncoras com erro de digitação: um fragmento que é uma grafia incorreta clara de um título real na página de destino (por exemplo, #instalation → #installation)
  • Desvio de âncora entre idiomas: uma página traduzida renomeou seus títulos, mas os links nesse idioma ainda apontam para o fragmento antigo em inglês (por exemplo, /fr/ai/selectors#ai-strategies → /fr/ai/selectors#stratégies-ia)

Execute jamdesk broken-links para ver o que precisa ser corrigido:

jamdesk broken-links

Revise a saída. jamdesk fix atua sobre avisos em que consegue associar uma âncora provável a um título real.

Etapa 2: Visualizar as correções

Execute com --dry-run para ver o que mudaria sem gravar arquivos:

jamdesk fix --dry-run

Exemplo de saída:

Planned fixes:

  fr/ai/overview.mdx:9
    /fr/ai/selectors#ai-strategies  →  /fr/ai/selectors#stratégies-ia

(dry run — no files written)

Verifique cada correção planejada. Se alguma alteração parecer incorreta, corrija esse link manualmente.

Etapa 3: Aplicar as correções

Execute sem --dry-run para aplicar. A CLI pede confirmação:

jamdesk fix
Apply 1 fix(es) to local files? (y/N)

Pressione y para gravar as alterações. Pule o prompt em CI ou scripts com -y:

jamdesk fix -y

O comando então exibe:

Fixed 1 file(s); 0 warning(s) left for manual review.

jamdesk fix deixa para você, para correção manual, qualquer aviso com destino ambíguo.

Etapa 4: Revisar o diff e fazer commit

Verifique as alterações antes de fazer commit:

git diff

Confirme que cada link reescrito aponta para onde você espera. Depois faça o commit:

git add -A
git commit -m "fix(docs): auto-fix broken internal links"

Uso com um agente de IA

jamdesk fix --json imprime o plano de correção como um único documento JSON para um agente de programação, como o Claude Code. Ele não grava arquivos nem faz perguntas. O agente faz as edições. Requer a CLI 1.1.229 ou posterior.

jamdesk fix --json

Exemplo de saída (resumida):

{
  "version": 1,
  "fixes": [
    {
      "type": "broken_link",
      "file": "fr/ai/overview.mdx",
      "line": 9,
      "oldText": "/fr/ai/selectors#ai-strategies",
      "newText": "/fr/ai/selectors#stratégies-ia",
      "resolvedBy": "deterministic"
    },
    {
      "type": "description",
      "file": "setup.mdx",
      "text": "How to set up the CLI.",
      "resolvedBy": "ai"
    }
  ],
  "unfixable": [
    {
      "type": "broken_link",
      "file": "quickstart.mdx",
      "line": 4,
      "link": "/missing",
      "reason": "points at a page that doesn't exist; create it or fix the link"
    }
  ],
  "notes": []
}

O documento tem três listas:

  • fixes: as edições a fazer. Para um broken_link, substitua oldText por newText nessa linha. Uma description é uma sugestão de IA para o frontmatter da página, então o agente deve mostrá-la a você antes de gravá-la.
  • unfixable: problemas a corrigir manualmente, cada um com um motivo.
  • notes: mensagens da execução, por exemplo quando correções de IA foram ignoradas.

Se a execução falhar, a saída é {"version": 1, "error": "..."} e o comando sai com código 1.

Para começar, peça ao seu agente algo como: "Execute jamdesk fix --json, aplique as correções de links e me mostre as descrições antes de adicioná-las."

Opções

FlagDescrição
--dry-runVisualiza as correções planejadas sem gravar arquivos
-y, --yesAplica as correções sem pedir confirmação
--types <list>Tipos de aviso separados por vírgula a corrigir (padrão: todos os suportados)
--no-aiIgnora as correções de IA e usa apenas as correções que o Jamdesk consegue determinar sem IA
--project <id>ID do projeto para correções de IA (padrão: projectId em docs.json)
--jsonImprime o plano de correção e os problemas que não pode corrigir como JSON. Não grava arquivos nem pergunta nada

O que vem a seguir?

Corrigir com IA

Corrija problemas no painel e faça commit no GitHub

Visão geral da CLI

Referência completa de comandos

Links e navegação

Como os links internos são detectados e resolvidos