Broken Links beheben

jamdesk fix repariert, was jamdesk broken-links meldet. Es liest dieselben Warnungen und schreibt einen Link um, wenn es ein eindeutig korrektes Ziel findet. Mehrdeutige Fälle bleiben unverändert für die manuelle Prüfung.

Es behebt zwei Arten kaputter interner Links:

• Fehlerhafte Anker: ein Fragment, das eine eindeutige Falschschreibung einer echten Überschrift auf der Zielseite ist (z. B. #instalation → #installation)
• Anker-Drift zwischen Sprachen: Eine übersetzte Seite hat ihre Überschriften umbenannt, aber Links in dieser Sprache zeigen noch auf das alte englische Fragment (z. B. /fr/ai/selectors#ai-strategies → /fr/ai/selectors#stratégies-ia)

Schritt 1: Defekte Links finden

Führen Sie jamdesk broken-links aus, um zu sehen, was behoben werden muss:

jamdesk broken-links

Prüfen Sie die Ausgabe. jamdesk fix zielt auf Warnungen, bei denen es einen wahrscheinlichen Anker mit einer echten Überschrift abgleichen kann.

Schritt 2: Korrekturen in der Vorschau anzeigen

Führen Sie den Befehl mit --dry-run aus, um zu sehen, was sich ändern würde, ohne Dateien zu schreiben:

jamdesk fix --dry-run

Beispielausgabe:

Planned fixes:

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

(dry run — no files written)

Prüfen Sie jede geplante Korrektur. Wenn eine Änderung falsch aussieht, korrigieren Sie diesen Link stattdessen von Hand.

Schritt 3: Korrekturen anwenden

Führen Sie den Befehl ohne --dry-run aus, um sie anzuwenden. Die CLI bittet um Bestätigung:

jamdesk fix

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

Drücken Sie y, um die Änderungen zu schreiben. In CI oder Skripten überspringen Sie die Abfrage mit -y:

jamdesk fix -y

Der Befehl gibt anschließend aus:

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

jamdesk fix lässt eine Warnung mit einem mehrdeutigen Ziel für Sie zur manuellen Korrektur stehen.

Schritt 4: Diff prüfen und committen

Prüfen Sie die Änderungen vor dem Commit:

git diff

Stellen Sie sicher, dass jeder umgeschriebene Link dorthin zeigt, wo Sie es erwarten. Committen Sie dann:

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

Verwendung mit einem KI-Agenten

jamdesk fix --json gibt den Korrekturplan als ein einziges JSON-Dokument für einen Coding-Agenten wie Claude Code aus. Es werden keine Dateien geschrieben und keine Fragen gestellt. Der Agent nimmt die Änderungen vor. Erfordert CLI 1.1.229 oder neuer.

jamdesk fix --json

Beispielausgabe (gekürzt):

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

Das Dokument enthält drei Listen:

• fixes: Die vorzunehmenden Änderungen. Bei einem broken_link ersetzen Sie oldText durch newText in dieser Zeile. Eine description ist ein KI-Vorschlag für das Frontmatter der Seite, daher sollte der Agent sie Ihnen vor dem Schreiben zeigen.
• unfixable: Probleme, die von Hand behoben werden müssen, jeweils mit einem Grund.
• notes: Meldungen aus dem Lauf, zum Beispiel wenn KI-Korrekturen übersprungen wurden.

Schlägt der Lauf fehl, lautet die Ausgabe {"version": 1, "error": "..."} und der Befehl endet mit Exit-Code 1.

Zum Starten können Sie Ihrem Agenten etwa Folgendes sagen: „Führe jamdesk fix --json aus, wende die Link-Korrekturen an und zeige mir die Beschreibungen, bevor du sie hinzufügst."

Optionen

Wie geht es weiter?