Fix Broken Links

jamdesk fix repairs what jamdesk broken-links reports. It reads the same warnings and rewrites a link when it finds one clear correct target. It leaves ambiguous cases untouched for manual review.

It fixes two types of broken internal links:

• Typo'd anchors: a fragment that's a clear misspelling of a real heading on the target page (e.g. #instalation → #installation)
• Cross-locale anchor drift: a translated page renamed its headings, but links in that locale still point at the old English fragment (e.g. /fr/ai/selectors#ai-strategies → /fr/ai/selectors#stratégies-ia)

Step 1: Find broken links

Run jamdesk broken-links to see what needs fixing:

jamdesk broken-links

Review the output. jamdesk fix targets warnings where it can match a likely anchor to a real heading.

Step 2: Preview the fixes

Run with --dry-run to see what would change without writing files:

jamdesk fix --dry-run

Example output:

Planned fixes:

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

(dry run — no files written)

Check each planned fix. If a change looks wrong, fix that link by hand instead.

Step 3: Apply the fixes

Run without --dry-run to apply. The CLI asks you to confirm:

jamdesk fix

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

Press y to write the changes. Skip the prompt in CI or scripts with -y:

jamdesk fix -y

The command then prints:

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

jamdesk fix leaves a warning with an ambiguous target for you to fix by hand.

Step 4: Review the diff and commit

Check the changes before committing:

git diff

Verify that each rewritten link points where you expect. Then commit:

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

Use with an AI agent

jamdesk fix --json prints the fix plan as one JSON document for a coding agent such as Claude Code. It writes no files and asks no questions. The agent makes the edits. Needs CLI 1.1.229 or later.

jamdesk fix --json

Example output (trimmed):

{
  "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": []
}

The document has three lists:

• fixes: the edits to make. For a broken_link, replace oldText with newText on that line. A description is an AI suggestion for the page's frontmatter, so the agent should show it to you before writing it.
• unfixable: issues to fix by hand, each with a reason.
• notes: messages from the run, for example when AI fixes were skipped.

If the run fails, the output is {"version": 1, "error": "..."} and the command exits with code 1.

To start, ask your agent something like: "Run jamdesk fix --json, apply the link fixes, and show me the descriptions before you add them."

Options

What's Next?