Ihre Dokumentationswebsite verwalten

Dieser Leitfaden behandelt, was Sie nachdem Ihre Website online gegangen ist, tun: Seiten ändern, eine Änderung rückgängig machen, festlegen, wer sie lesen kann, und eine Website diagnostizieren, die Ihren letzten Commit nicht übernommen hat. Wenn Sie noch keine Website veröffentlicht haben, beginnen Sie mit Erstellen Ihrer ersten Dokumentationswebsite.

Verwaltungs-Widget öffnen#

Melden Sie sich an und öffnen Sie Ihre eigene Website. In der unteren rechten Ecke wird ein Verwaltungs-Widget angezeigt:

+----------------------+
| Your name            |
|                      |
| Select chat        > |
| Select repo        > |
| Select mode        > |
|                      |
| Settings             |
| Sign out             |
+----------------------+

Klicken Sie auf Ihren Avatar oder auf Einstellungen, um das Einstellungsfenster zu öffnen. Alles auf dieser Seite, auf dem „Einstellungen“ steht, beginnt hier.

Leser sehen dieses Widget nie. Abgemeldete Besucher sehen Ihre Dokumentation, Ihr Design und Ihre Inhalte, aber keine der Steuerelemente.

Was Sie in den Einstellungen konfigurieren können#

Eine Seite von GitHub aktualisieren#

1. Öffnen Sie Ihr Repository auf github.com.
2. Öffnen Sie die Markdown-Datei und klicken Sie auf das Stiftsymbol.
3. Nehmen Sie Ihre Änderung vor und klicken Sie auf Änderungen committen.

Ihre Website übernimmt den Commit automatisch. Eine erneute Bereitstellung ist nicht erforderlich.

Seiten von Ihrem Computer mit Git aktualisieren#

Verwenden Sie dies, wenn Sie mehrere Dateien gleichzeitig ändern und gemeinsam überprüfen lassen möchten.

git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git
cd YOUR_REPO

Bearbeiten Sie die Dateien in Ihrem Editor und veröffentlichen Sie sie anschließend:

git add docs/
git commit -m "Update the installation guide"
git push origin main

Das Löschen einer Seite folgt demselben Ablauf: Datei löschen, Commit erstellen, pushen. Die Seite verschwindet von der Website und aus der Seitenleiste.

Eine Seite bearbeiten, ohne den Browser zu verlassen#

Für eine kleine Korrektur benötigen Sie weder GitHub noch einen lokalen Checkout – bearbeiten Sie einfach die Seite, die Sie gerade lesen.

1. Öffnen Sie das Projekt im Docsbook-AI-Chat mit der daneben angezeigten Vorschau (geteilte Ansicht).
2. Wechseln Sie in der Leiste über der Vorschau von Vorschau zu Bearbeiten.
3. Klicken Sie auf den Block, den Sie ändern möchten.

Das daraufhin geöffnete Bedienfeld kann den Block mit KI neu formulieren, seinen Text direkt bearbeiten, ihn kürzen oder erweitern, ihn in ein Inhalts-Widget umwandeln oder ihn entfernen. Ziehen Sie einen Block an seinem Griff, um ihn zu verschieben; die neue Reihenfolge wird in der Vorschau angezeigt, bis Sie auf Speichern oder Verwerfen klicken.

Wenn Sie etwas hinzufügen statt ändern möchten, bewegen Sie den Mauszeiger auf die Trennlinie zwischen zwei Blöcken. Eine Plus-Schaltfläche erscheint und bietet einen Absatz, eine Überschrift, eine Liste, einen Codeblock, ein Zitat, einen Hinweis, eine Tabelle oder ein Widget an. Seite hinzufügen am unteren Rand der Seitenleiste erstellt eine vollständige Seite aus einem Titel, einem Ordner und einer optionalen Notiz dazu, was sie abdecken soll.

Jede dieser Aktionen wird wie jede andere Änderung in Ihrem Repository gespeichert, sodass Ihre Quelle die einzige maßgebliche Quelle bleibt. Das Neufomulieren eines Blocks mit KI ruft ein Modell auf und wird mit dem Guthaben des Projekts verrechnet; die eigenständige Bearbeitung des Textes ist kostenlos.

Eine veröffentlichte Änderung rückgängig machen#

Jede vom Assistenten veröffentlichte Änderung kann direkt aus dem Chat rückgängig gemacht werden, ohne GitHub zu öffnen.

• Sofort: Klicken Sie auf dem Änderungsfeld, das der Assistent nach der Veröffentlichung anzeigt („2 Dateien aktualisiert“), auf den Rückgängig-Pfeil.
• Später: Öffnen Sie das Uhrsymbol in der Chat-Kopfzeile. Es listet die letzten Änderungen des Projekts mit den jeweils betroffenen Dateien sowie einer Rückgängig-Option neben jedem Eintrag auf.

Dieser Verlauf ist der tatsächliche Veröffentlichungsverlauf Ihres Repositorys. Daher werden auch Änderungen aufgeführt, die in einer früheren Sitzung, von einem Teammitglied oder direkt auf GitHub vorgenommen wurden. Alle können auf dieselbe Weise rückgängig gemacht werden.

Das Rückgängigmachen erstellt einen neuen Commit, der die Dateien zurücksetzt, und schreibt nicht den Verlauf um. Es erscheint in der Liste als eigener Eintrag mit der Markierung Rückgängig, kann selbst rückgängig gemacht werden und verwirft niemals die Commits anderer Personen. Wenn eine frühere Version einer Datei nicht erneut gelesen werden kann, wird dies als übersprungen gemeldet, statt die Datei zu erraten.

Den Assistenten fragen, was verbessert werden sollte#

Fragen Sie den Assistenten, was behoben werden sollte – „was sollte ich zuerst beheben“, „mach das in der Suche auffindbar“, „diese Seiten wirken dünn“ – und die Antwort kommt als Liste zurück, die Sie abhaken, statt als Text, den Sie von Hand umsetzen müssten.

Jede Zeile steht für eine konkrete Änderung an einer Ihrer tatsächlichen Seiten: was geändert wird, warum es hilft und welche Seite betroffen ist. Einige Zeilen betreffen eine Einstellung statt einer Überarbeitung und öffnen die Karte, mit der Sie diese Einstellung umschalten. Zu Beginn ist nichts abgehakt. Haken Sie die gewünschten Zeilen ab, drücken Sie einmal auf Apply, und jede abgehakte Zeile wird in einem einzigen Durchlauf erledigt. Nicht abgehakte Zeilen werden niemals geschrieben.

Die Liste beruht nicht auf Vermutungen: Der Assistent liest den Dokumentations-Skill zu Ihrem Anliegen – Suche und Indexierung, Tonalität, Barrierefreiheit, Übersetzung –, prüft, was er über Ihre Website messen kann, prüft, welche Einstellungskarten vorhanden sind, und gibt auf Grundlage dieser Ergebnisse Empfehlungen. Er nennt den angewendeten Skill.

Was Apply bewirkt, hängt vom Auto-Modus ab:

Sowohl das Erstellen der Liste als auch das Überarbeiten der Seiten greifen auf ein KI-Modell zurück, daher werden beide Vorgänge vom Guthaben des Projekts abgezogen.

Die Reihenfolge der Seitenleiste verstehen#

Docsbook liest die Dateinamen, um die Seitenleiste zu sortieren:

• Seiten, die Leser an den Anfang führen — README, introduction, getting-started, quick-start, installation, setup — werden zuerst aufgeführt.
• Seiten zum Nachschlagen — reference, api, changelog, faq, troubleshooting — werden zuletzt aufgeführt.
• Alles andere wird alphabetisch dazwischen eingeordnet. Ordner werden anhand ihrer eigenen Namen auf dieselbe Weise eingeordnet.

Numerische Präfixe funktionieren daher weiterhin: 1-basics.md wird alphabetisch vor 2-intermediate.md sortiert, und die Zahl wird ignoriert, wenn Docsbook den Namen mit den beiden obigen Listen abgleicht.

Wenn keine deiner Seiten einer der beiden Listen entspricht, wird die Seitenleiste einfach alphabetisch sortiert. Benenne eine Datei um, um sie zu verschieben.

Dateien in Ordner organisieren#

Die Seitenleiste bildet Ihre Ordnerstruktur ab, daher ist die Struktur die Navigation. Gruppieren Sie nach Thema:

docs/
├── README.md
├── getting-started.md
├── api/
│   ├── overview.md
│   ├── auth.md
│   └── endpoints.md
└── guides/
    ├── deployment.md
    └── troubleshooting.md

Die Gruppierung nach Thema ist besser als die Gruppierung nach Schwierigkeitsgrad (1-basics.md, 2-advanced.md), weil ein Leser über eine Suchmaschine nach einem Thema sucht, nicht nach einem Niveau.

Verknüpfungen zwischen Seiten#

Schreiben Sie gewöhnliche relative Markdown-Links. Docsbook wandelt sie beim Veröffentlichen in URLs der Website um.

[Set up a custom domain](/docsbook-io/docs/guides/advanced/custom-domain)
[Create your first site](/docsbook-io/docs/guides/getting-started/creating-docs)
[Frequently asked questions](/docsbook-io/docs/faq)

Verknüpfen Sie mit einer Überschrift auf derselben Seite über deren Anker:

[Jump to the sidebar order](#understand-the-sidebar-order)

Der Anker entspricht dem Text der Überschrift in Kleinbuchstaben, wobei Leerzeichen durch Bindestriche ersetzt werden. Daher muss die Überschrift vorhanden sein, damit der Link zum richtigen Ziel führt.

Bilder hinzufügen#

1. Legen Sie die Bilddatei neben der Seite in Ihrem Repository ab, zum Beispiel in einem images/-Ordner.
2. Übernehmen Sie sie.
3. Verweisen Sie mit einem relativen Pfad darauf und beschreiben Sie, was sie zeigt:

![GitHub fork dialog with the Create fork button highlighted](https://raw.githubusercontent.com/docsbook-io/docs/main/guides/getting-started/images/fork-dialog.png)

PNG, JPG, GIF und WebP werden alle dargestellt. Schreiben Sie für jedes Bild, das Informationen vermittelt, einen aussagekräftigen Alternativtext – er wird von einem Screenreader vorgelesen, von einer Suchmaschine indexiert und von Lesern angezeigt, wenn die Datei nicht geladen werden kann.

Kontrollieren Sie, wer Ihre Dokumentation lesen kann#

Standardmäßig ist eine Docsbook-Website öffentlich: Jeder, der über den Link verfügt, kann sie lesen, Suchmaschinen-Crawler nehmen sie in den Index auf, und es ist kein GitHub-Konto erforderlich. Dies gilt auch dann, wenn das Quell-Repository privat ist.

Um den Zugriff zu schließen, stellen Sie den Workspace unter Settings → Privacy & Access auf privat. Leser müssen sie dann mit einem gemeinsamen Passwort oder durch die Anmeldung über Ihren eigenen OIDC-Identitätsanbieter entsperren – einschließlich Crawlern. Sie als Eigentümer haben immer Zugriff. Vollständige Einrichtung: Einschränken, wer Ihre Dokumentations-Website lesen kann.

Mit anderen zusammenarbeiten#

Über GitHub. Füge sie als Mitwirkende zum Repository hinzu. Sie bearbeiten Dateien oder öffnen Pull Requests, und die Website wird aktualisiert, sobald eine Änderung deinen Standard-Branch erreicht. Dies ist der richtige Weg für alle, die bereits im Repository arbeiten.

Über den KI-Chat. Klicke in der Chat-Symbolleiste auf Einladen und sende eine E-Mail-Einladung oder einen Link. Die Mitwirkenden nehmen an derselben Live-Sitzung teil, sodass sie kein GitHub-Konto benötigen. Ihre Arbeit greift auf dasselbe Projektguthaben zurück wie deine.

Eine Website reparieren, die nicht aktualisiert wurde#

Gehen Sie diese Schritte der Reihe nach durch.

1. Bestätigen Sie, dass der Commit GitHub erreicht hat. Öffnen Sie das Repository und suchen Sie danach. Wenn er nicht dort ist, wurde er nie gepusht.
2. Laden Sie die Seite über den Browser-Cache hinaus neu. Strg+F5 oder unter macOS Cmd+Umschalt+R. Ein privates Fenster ist der schnellste Weg, den Cache als Ursache auszuschließen.
3. Warten Sie ein paar Minuten. Die Veröffentlichung erfolgt nicht sofort; Docsbook überprüft das Repository regelmäßig und nicht bei jedem Tastendruck.
4. Überprüfen Sie die Dateierweiterung. Nur .md-Dateien werden veröffentlicht.
5. Überprüfen Sie den Dateinamen. Lateinische Buchstaben, Ziffern und Bindestriche sind unbedenklich; andere Zeichen führen möglicherweise nicht zu einer URL.

Wenn einige Seiten aktualisiert wurden und andere nicht, liegt es fast immer am Browser-Cache und nicht an der Synchronisierung — eine teilweise Aktualisierung ist kein Zustand, den Docsbook veröffentlicht.

Versionierung#

Docsbook stellt eine Version Ihrer Dokumentation bereit: den aktuellen Stand Ihres Branches. Mehrere veröffentlichte Versionen nebeneinander werden derzeit nicht unterstützt.

Wenn Sie sie jetzt benötigen, verwalten Sie die Versionen in separaten Branches (docs/v1, docs/v2) oder in separaten Repositorys und verbinden Sie das Repository, das Sie veröffentlichen möchten.

Sehen Sie, wer liest#

Öffnen Sie das Float Widget → Analytics. Aufrufe, Besucher, meistbesuchte Seiten, Verweise und Suchanfragen werden pro Seite erfasst. So sehen Sie, welche Seiten ihren Traffic verdienen und welche ungelesen bleiben.

Zwei Berichte beantworten die meisten Fragen zu einer Seite: Webanalysen für den Traffic und Seitenfeedback dafür, ob die angekommenen Leser das gefunden haben, was sie benötigten.

Arbeitsbereich löschen#

Einstellungen → Arbeitsbereich löschen entfernt die Dokumentationswebsite und alle darauf gespeicherten Einstellungen. Dies kann nicht rückgängig gemacht werden.

Dein GitHub-Repository bleibt unverändert. Das Markdown bleibt dort, wo es immer war. Beim Löschen eines Arbeitsbereichs gehen daher Konfigurationen, nicht Inhalte verloren.

Nächste Schritte#

• Eine benutzerdefinierte Domain einrichten — die Dokumentation über eine Adresse bereitstellen, die Ihnen gehört.
• Ihre Dokumentation übersetzen — 15 Sprachen, jeweils separat indexiert.
• Was Docsbook umfasst und was kostenpflichtig ist — welche Aktionen das Projektguthaben belasten.
• Häufig gestellte Fragen — die Fragen, die Leser stellen, bevor sie sich festlegen.