Mit KI beheben
Prüfen und übernehmen Sie KI-Vorschläge für defekte Links und fehlende Seitenbeschreibungen im Jamdesk-Dashboard und committen Sie die Änderungen in GitHub.
Wenn ein Build mit defekten Links oder Seiten ohne Beschreibung abgeschlossen wird, kann Jamdesk viele dieser Probleme für Sie beheben. Die Schaltfläche Fix with AI liest die Build-Warnungen, schlägt für jede davon eine konkrete Änderung vor und committet die von Ihnen genehmigten Korrekturen in Ihr verbundenes GitHub-Repository. Dadurch wird ein neuer Build gestartet. Diese Seite richtet sich an alle, die eine Jamdesk-Website pflegen und Build-Warnungen beseitigen möchten, ohne MDX manuell zu bearbeiten.
Eine lokale, terminalbasierte Variante derselben Funktion finden Sie im CLI-Befehl jamdesk fix. Der Dashboard-Ablauf committet die Änderungen für Sie; die CLI schreibt sie in Ihre Arbeitskopie und überlässt Ihnen den Commit.
Die Screenshots zeigen die Benutzeroberfläche auf Englisch.
Was wird behoben?
Fix with AI arbeitet mit drei Arten von Build-Warnungen:
- Defekte interne Links. Ein Linkfragment verweist auf eine Überschrift, die auf der Zielseite nicht mehr existiert, etwa wegen eines Tippfehlers (
#instalation→#installation) oder weil die Überschrift einer übersetzten Seite umbenannt wurde. - Fehlende Seitenbeschreibungen. Eine Seite enthält in ihrem Frontmatter keine
description. Jamdesk erstellt aus dem Seiteninhalt eine kurze Zusammenfassung, die Sie prüfen können. - Fehlende Seitentitel. Für eine Seite ohne Titel wird aus dem Seiteninhalt ein Titel vorgeschlagen, den Sie prüfen können.
Eine Änderung wird nur vorgeschlagen, wenn das Ziel mit ausreichender Sicherheit ermittelt werden kann. Alles Uneindeutige bleibt unverändert und wird separat aufgeführt, damit Sie es manuell beheben können.
Die Zahl der behebbaren Probleme entspricht nicht der Zahl der Warnungen. Ein Build kann fünf Warnungen anzeigen, während Fix with AI nur drei davon beheben kann, weil für die anderen beiden keine eindeutige Lösung vorliegt. Das Banner zeigt immer an, was tatsächlich behoben werden kann.
Voraussetzungen
- Ein verbundenes GitHub-Repository für das Projekt.
- Schreibzugriff für die Jamdesk GitHub App, damit sie die Korrekturen committen kann. Fehlt der Zugriff, zeigt das Modal einen Link Grant access, über den Sie zu GitHub gelangen und den Zugriff hinzufügen können.
- Ein abgeschlossener Build mit Warnungen zu defekten Links oder fehlenden Beschreibungen.
Banner finden
Öffnen Sie Ihr Projekt und scrollen Sie auf der Projektstartseite zum Bereich Build History. Wenn Ihr neuester Build behebbare Probleme enthält, erscheint über der Build-Liste ein Banner mit der Anzahl der Probleme und einer Schaltfläche Fix with AI.
Das Banner wird nur für Ihren neuesten abgeschlossenen Build angezeigt. Ältere Builds im Verlauf enthalten es nicht, da Korrekturen immer auf den aktuellen Stand Ihrer Dokumentation angewendet werden.
Fixes prüfen und anwenden
Klicken Sie auf Fix with AI. Das Modal wird geöffnet, und der KI-Agent prüft Ihre Dokumentation, um einen Korrekturplan zu erstellen. Dies dauert einige Sekunden.
Korrekturen werden nach Typ gruppiert. Broken links zeigt jedes umgeschriebene Ankerziel, Missing descriptions die vorgeschlagene Zusammenfassung für jede Seite und Missing titles den vorgeschlagenen Titel. Deaktivieren Sie das Kontrollkästchen für alle Änderungen, die Sie diesmal überspringen möchten, oder verwenden Sie die Ignorieren-Schaltfläche, um eine Empfehlung dauerhaft auszublenden. Probleme ohne eindeutige Korrektur erscheinen unter Can't be fixed automatically und müssen von Ihnen manuell bearbeitet werden.
Klicken Sie auf Apply fixes. Jamdesk committet die ausgewählten Änderungen mit der Nachricht docs: apply AI-suggested fixes (via Jamdesk) in Ihren verbundenen Branch und startet einen neuen Build.
Beobachten Sie den neuen Build unter Build History. Sobald er live ist, sind die behobenen Warnungen verschwunden. Alles, was verbleibt, ist entweder eine Warnung, die Fix with AI nicht auflösen konnte, oder ein neues Problem aus den neuesten Inhalten.
Beim Anwenden wird ein echter Commit in Ihrem Repository erstellt. Die Änderung wird daher in Ihrer Git-Historie erfasst und kann auf GitHub wie jeder andere Commit geprüft oder zurückgesetzt werden.
Wenn manche Probleme nicht behoben werden können
Wenn es für eine Warnung keine eindeutige Korrektur gibt, listet das Modal sie unter einer separaten Überschrift auf und lässt sie unverändert. Häufige Gründe:
- Ein defekter Link, dessen Zielseite oder Zielüberschrift nirgends existiert, sodass es kein mögliches Ziel gibt.
- Ein Navigationseintrag ohne passende Quelldatei.
- Eine Seite, für die der Agent nicht automatisch eine Beschreibung erstellen konnte.
Diese Probleme müssen manuell bearbeitet werden. Öffnen Sie die Seite im Editor oder in Ihrem Code-Editor, korrigieren Sie den Link oder fügen Sie die Beschreibung hinzu und pushen Sie anschließend, um einen neuen Build zu starten.
Empfehlungen ignorieren
Manche Warnungen müssen nicht bearbeitet werden: etwa ein Link, den Sie absichtlich unbrauchbar gemacht haben, oder eine Platzhalterseite, die keine Beschreibung benötigt. Wenn Sie eine Korrektur deaktivieren, wird sie nur einmal übersprungen. Durch das Ignorieren wird sie aus der Anzahl entfernt, bis Sie sie wiederherstellen.
Jede Zeile im Modal verfügt über eine Ignorieren-Schaltfläche, unabhängig davon, ob sie behoben werden kann. Klicken Sie darauf, und das Element wird in einen eingeklappten Abschnitt Ignored am unteren Rand verschoben. Sobald Sie das Modal schließen, sinkt die Anzahl im Banner auf der Projektstartseite entsprechend. Die zugehörigen Warnungen verschwinden aus Build History, sowohl im aktuellen Build als auch in allen folgenden Builds. Ignore all führt dies für alle weiterhin aufgeführten Elemente durch.
So funktionieren ignorierte Empfehlungen:
- Gemeinsam und dauerhaft. Ignorierte Empfehlungen gelten für das gesamte Projekt. Daher sehen alle Mitglieder dieselbe Liste, und die Ignorierungen bleiben über mehrere Builds hinweg bestehen. Jamdesk ordnet jede Warnung anhand ihres Inhalts statt anhand ihrer Zeilennummer zu. Wenn Sie andere Teile der Seite bearbeiten, wird ein ignoriertes Element daher nicht erneut angezeigt.
- Wiederherstellen. Klappen Sie den Abschnitt Ignored auf und klicken Sie bei einem Element auf Restore. Wenn Sie alle Elemente eines Builds ignorieren, verschwindet das Banner. Ein kleiner Link „N ignored recommendations“ unter Build History öffnet das Modal erneut.
- Geänderte Warnungen werden erneut angezeigt. Wenn sich das zugrunde liegende Problem ändert, etwa weil der defekte Link nun auf ein anderes Ziel verweist, stimmt es nicht mehr mit dem ignorierten Eintrag überein und wird als neue Empfehlung angezeigt.
Mit KI beheben vs. CLI
Beide Tools korrigieren Ankerziele defekter Links. Sie unterscheiden sich darin, wo sie ausgeführt werden und wie die Änderung übernommen wird.
| Fix with AI (Dashboard) | jamdesk fix (CLI) | |
|---|---|---|
| Ausführung | Im Dashboard für einen Build | In Ihrem Terminal für lokale Dateien |
| Korrekturen | Defekte Links und fehlende Beschreibungen | Ankerziele defekter Links |
| Commit | Committet die Änderungen für Sie in Ihren Branch | Schreibt lokale Dateien; Sie erstellen den Commit |
| Auslöser | Ein Klick auf das Build-Banner | jamdesk fix |
Verwenden Sie den Dashboard-Ablauf für eine schnelle Korrektur, ohne Jamdesk zu verlassen. Verwenden Sie die CLI, wenn die Änderungen zunächst in Ihrer Arbeitskopie vorliegen sollen, etwa um sie mit anderen Bearbeitungen zu bündeln.