Docsbook-Konzepte: Arbeitsbereich, Projektbalance, Indexierung

Jeder Begriff, den die Benutzeroberfläche und Dokumentation von Docsbook verwenden, ist hier einmal definiert. Jeder Eintrag enthält zunächst eine Definition in einem Satz und anschließend, wo Ihnen der Begriff begegnet und was er beeinflusst. Die Begriffe sind gruppiert; innerhalb der Gruppen sind sie alphabetisch geordnet.

Die Website und ihre Inhalte#

Arbeitsbereich#

Ein Arbeitsbereich ist eine Dokumentationswebsite mit ihren Einstellungen, die auf einem Repository mit Markdown-Dateien basiert. Das Repository befindet sich entweder in deinem eigenen GitHub-Konto oder wird von Docsbook für dich gehostet, wenn du mit einem Website-Scan oder einem schriftlichen Briefing begonnen hast.

Ein Arbeitsbereich umfasst seine Adresse, sein Erscheinungsbild, seine Spracheinstellungen, seine Analysedaten und sein Guthaben. Das Admin-Panel und die Abrechnungsseiten von Docsbook bezeichnen dasselbe Objekt als Projekt; beide Begriffe bedeuten dasselbe.

Entwurf#

Ein Entwurf ist eine generierte Dokumentationswebsite, die noch nicht veröffentlicht wurde. Docsbook erstellt einen solchen Entwurf aus deiner Quelle, bevor du ein Konto hast.

Ein Entwurf aus dem Scan einer Website oder aus einem schriftlichen Briefing bleibt in deinem Browser, bis du ihn veröffentlichst. Ein Entwurf wird in demselben Admin-Bereich geöffnet, den auch ein veröffentlichter Arbeitsbereich erhält, sodass Branding, Layout und SEO vor der Anmeldung festgelegt werden können.

Seite#

Eine Seite ist eine einzelne Markdown-Datei im Workspace-Repository, die unter ihrer eigenen URL bereitgestellt wird. Datei- und Ordnernamen bestimmen die URL und die Position im Navigationsbaum.

Die Erweiterungen .md und .markdown werden gelesen. Dateien in anderen Formaten – .txt, .rst – werden nicht in Seiten umgewandelt.

Navigationsbaum#

Der Navigationsbaum ist die Seitenleiste, die Docsbook aus der Ordnerstruktur Ihres Repositorys erstellt. Ein Ordner wird zu einer Gruppe, eine Datei zu einem Eintrag darunter.

README.md im Stammverzeichnis eines Ordners wird zur Landingpage dieses Ordners. Sie müssen keine Navigationsdatei erstellen: Wenn Sie eine Datei im Repository verschieben, wird sie auch in der Seitenleiste verschoben.

Gliederung#

Die Gliederung ist das seitenbezogene Inhaltsverzeichnis, das Docsbook aus den Überschriften dieser Seite erstellt und rechts neben dem Inhalt anzeigt. Wenn Sie auf eine Überschrift klicken, wird die Seite dorthin gescrollt.

Die Gliederung wird aus Überschriften der Ebene H2 und niedriger erstellt. Wenn eine Überschriftenebene übersprungen wird, entsteht darin eine Lücke.

Inhalts-Widget#

Ein Inhalts-Widget ist ein Bereich einer Markdown-Seite, den Docsbook als erweiterten Block rendert – ein Kartenraster, ein Akkordeon, nummerierte Schritte oder eine Handlungsaufforderung –, der durch zwei HTML-Kommentare gekennzeichnet ist.

Die Kommentare sind in jedem anderen Markdown-Reader unsichtbar, sodass dieselbe Datei weiterhin auf GitHub korrekt gelesen wird. Ein unbekannter Widget-Name wird zu gewöhnlichem Markdown; nichts wird jemals ausgeblendet. Siehe Inhalts-Widgets.

Wie Inhalte hineingelangen und aktuell bleiben#

Indizierung#

Indizierung ist der Vorgang, den Docsbook auf Ihr Markdown anwendet, um alles zu erstellen, was die Website benötigt: den Suchindex, den Navigationsbaum, die Gliederung pro Seite, den Linkgraphen und die Einbettungen, aus denen der KI-Chat Informationen abruft.

Die Indizierung wird ausgeführt, wenn ein Arbeitsbereich erstellt wird, und erneut, sobald Docsbook geänderte Inhalte erkennt. Eine Seite, die nicht indiziert wurde, kann weder über die Suche gefunden noch vom Chat zitiert werden.

GitHub-Synchronisierung#

GitHub-Synchronisierung sorgt dafür, dass eine Docsbook-Website mit ihrem Repository auf dem neuesten Stand bleibt: Docsbook prüft beim Besuch der Website auf neue Commits auf GitHub und indiziert die Änderungen neu. Es muss kein Webhook konfiguriert werden, und es gibt keinen Build-Schritt, auf den gewartet werden muss.

Synchronisiert werden: neue .md-Dateien, Textänderungen, Löschungen, Umbenennungen und neue Ordner. Nicht synchronisiert werden: Commit-Verlauf, Branch-Informationen, Codekommentare und Dateien in anderen Formaten.

Maßgebliche Quelle#

Eine maßgebliche Quelle ist ein Repository oder eine Website, die Sie mit einem Arbeitsbereich verbunden haben, damit ein Agent, der Ihre Dokumentation erstellt, daraus Fakten liest, anstatt sich auf sein Erinnerungsvermögen zu verlassen. Jede verbundene Quelle enthält eine eigene Notiz des Eigentümers darüber, warum sie verbunden ist.

Quellen sind schreibgeschützte Eingaben. Sie sind vom Repository getrennt, aus dem die Website erstellt wird. Siehe Verbundene Quellen.

Web-Editor#

Der Web-Editor ist der browserbasierte Editor von Docsbook für die Markdown-Dateien des Workspace. Beim Speichern werden die Änderungen in das Repository übernommen, aus dem die Website erstellt wird.

Änderungen, die im Web-Editor, in GitHub oder von einem Agenten über MCP vorgenommen werden, landen alle im selben Repository, sodass es eine gemeinsame Historie statt zweier gibt.

Geld und Abrechnung#

Projektguthaben#

Ein Projektguthaben ist das Geld, das einem Arbeitsbereich zugeordnet ist und für die KI-Arbeit ausgegeben wird, die für diesen Arbeitsbereich erledigt wird. Jedes neue Projekt wird mit einem Guthaben von 1,00 $ erstellt. Zusätzlich kann der Eigentümer 5,00 $ beanspruchen, sobald das Projekt 3 Minuten alt ist. Danach wird das Guthaben über die Abrechnungsseite aufgeladen.

Guthaben gelten pro Projekt, nicht pro Konto: Wenn bei einem Projekt das Guthaben aufgebraucht ist, wird ein anderes dadurch nicht angehalten. Siehe Preise.

Aufladung#

Eine Aufladung ist eine Zahlung auf das Guthaben eines Projekts in einer von Ihnen festgelegten Höhe. Die kleinste einzelne Aufladung beträgt $20.00 und die größte $5,000.00.

Aufladungen verfallen nicht, und es wird kein Guthaben nach einem Zeitplan aufgefüllt. Eine wiederkehrende monatliche Zahlung kann auf der Abrechnungsseite eingerichtet werden; sie lädt dasselbe Guthaben jeden Monat auf.

Nutzungsabhängige Arbeit#

Nutzungsabhängige Arbeit ist die Arbeit, die ein Projektguthaben belastet. Es gibt genau vier Arten, und jede davon ist eine Zeile unter Ausgaben nach Quelle auf der Karte „Limits“ des Projekts:

• Leser (KI-Chat) — eine KI-Antwort, die einem Leser der veröffentlichten Dokumentation gegeben wird.
• Admin & KI-Agent — eine Agentenausführung einschließlich nutzungsabhängiger MCP-Tool-Aufrufe.
• KI-Übersetzungen — die Übersetzung einer Seite in eine andere Sprache.
• Semantischer Index — die Erstellung der Embeddings, aus denen der KI-Chat abruft.

Nichts anderes wird nutzungsabhängig abgerechnet: Hosting, eine benutzerdefinierte Domain und ihr TLS-Zertifikat, Leser, Bearbeiter, die GitHub-Synchronisierung, die Volltextsuche, Branding, Analysen und MCP-Leseaufrufe kosten pro Nutzung nichts. Jede der vier Quellen kann für den Abrechnungszeitraum auf der Karte „Limits“ begrenzt werden, und ein Limit von 0 $ deaktiviert diese Quelle.

Aufschlag#

Aufschlag ist der Prozentsatz, den Docsbook auf den tatsächlichen Preis des KI-Anbieters für das Modell aufschlägt, das die Antwort geliefert hat – derzeit 900 %. Das Modell, sein Preis pro 1 Mio. Token und der Aufschlag werden alle im Dashboard angezeigt.

Wenn Sie Ihren eigenen API-Schlüssel des Anbieters verwenden, entfällt der Aufschlag: Sie zahlen den Anbieter direkt, und Docsbook berechnet Ihnen für diese Nutzung nichts.

Wer kann die Website lesen#

Öffentliche Website#

Eine öffentliche Website ist die Standardeinstellung: Jeder, der über den Link verfügt, kann sie lesen, einschließlich Personen ohne GitHub-Konto und Suchmaschinen-Crawlern. Die Sichtbarkeit des Repositorys selbst ändert daran nichts – Docsbook liest das Repository und stellt dann die von ihm erstellten Seiten bereit.

Öffentlich sorgt dafür, dass die Website von Google indexiert und von KI-Assistenten zitiert werden kann.

Private Website#

Eine private Website zeigt allen außer dem Eigentümer einen Entsperrbildschirm anstelle Ihrer Inhalte an. Der Zugriff ist durch ein gemeinsames Passwort oder Ihren eigenen SSO-Identitätsanbieter geschützt. Struktur, Seiten und der Suchindex bleiben verborgen, bis ein Leser die Website entsperrt.

Der Eigentümer hat unabhängig von der Sichtbarkeit immer vollständigen Zugriff. Siehe Private Dokumentation: Passwort und SSO.

Benutzerdefinierte Domain#

Eine benutzerdefinierte Domain ist Ihr eigener Hostname – docs.yourcompany.com –, über den der Workspace anstelle von docsbook.io/{owner}/{repo} bereitgestellt wird. Sie fügen einen CNAME-Eintrag hinzu, und Docsbook stellt das TLS-Zertifikat bereit.

Die Adresse docsbook.io bleibt auch nach dem Hinzufügen einer benutzerdefinierten Domain funktionsfähig. Siehe Einrichtung einer benutzerdefinierten Domain.

Von Maschinen gelesene Oberflächen#

llms.txt#

llms.txt ist ein Klartextindex einer Docsbook-Website, der im Stammverzeichnis der Website für KI-Agenten bereitgestellt wird, die nach einem solchen Index suchen. Er listet die Seiten und den jeweiligen Inhalt auf.

Docsbook generiert ihn aus den indizierten Inhalten, sodass er nicht unabhängig von der Website veraltet. Siehe llms.txt.

MCP-Server#

Der MCP-Server ist der Model-Context-Protocol-Endpunkt von Docsbook unter https://docsbook.io/api/mcp/server und stellt 140 Tools bereit, mit denen ein KI-Agent den docsbook_expert-Agenten fragen kann, was zu tun ist, und Anweisungen zurückerhält, Ihre Dokumentation lesen und durchsuchen, Einstellungen ändern und Seiten zurückschreiben kann. Die Authentifizierung erfolgt als Bearer über OAuth 2.0 mit PKCE.

Discovery-Aufrufe werden nie abgerechnet; andere Aufrufe belasten das Projektguthaben. Siehe MCP-Server und die Referenz der MCP-Tools.

Float-Widget#

Das Float-Widget ist das Steuerungsmenü in der unteren rechten Ecke deiner eigenen veröffentlichten Dokumentation. Es ist nur für dich sichtbar, solange du angemeldet bist. Leser sehen es nie.

Es wechselt zwischen Chat, Repository und Modus, öffnet die Einstellungen und meldet dich ab.

Verwandte Themen#

• Übersicht — wie diese Elemente von Anfang bis Ende zusammenpassen
• Schnellstart — das Tutorial, das diese Begriffe in der richtigen Reihenfolge verwendet
• Referenz zu MCP-Tools — jedes Tool, seine Parameter und seine Preisklasse
• Preise — was abgerechnet wird und wofür ein Projektguthaben verwendet wird