Guidedog¶
English · 简体中文 · 日本語 · 한국어 · हिन्दी · Español · Deutsch
Einmal schreiben. Klar erklären. Im Web und auf Papier veröffentlichen.
Guidedog erzeugt HTML-Dokumentation und PDF-Bücher aus reStructuredText und Markdown. Es ist in Odin geschrieben. Die Konvertierungsengine heißt Guidedoc; Typst setzt die PDF-Seiten. Python oder LaTeX sind nicht nötig.
Sphinx dient als Vorbild für den Schreibablauf. Guidedog ist ein eigenständiges System: deklarative TOML-Konfiguration, statische API-Analyse und keine Ausführung von Python-Konfiguration oder -Erweiterungen. Vollständige Sphinx-Kompatibilität ist kein Ziel.
Ein Projekt beginnen¶
guidedog quickstart docs
guidedog build html docs
guidedog build pdf docs
guidedog serve docs
Das Projekt enthält conf.toml, index.rst, _templates/layout.html, _templates/book.typ und _static/. Vorlagen sind gewöhnliche, bearbeitbare Dateien. HTML bietet Navigation, Suche, hervorgehobenen Code, Diagramme und Gleichungen. PDF bietet Kapitel, Querverweise, Abbildungen, Register und sprachgerechten Satz.
Standard ist das helle Thema; Dunkel- und Systemthema sind wählbar. Die Einstiegsseiten des Handbuchs und der Repositoryübersicht erkennen die Browsersprache. Eine gespeicherte Wahl hat Vorrang; direkte Links zu einer Ausgabe oder einem Kapitel bleiben maßgeblich.
guidedog convert notes.md --to pdf --output notes.pdf
guidedog clean docs
guidedog migrate conf.py
Installieren¶
Jedes Release enthält ein Archiv für Linux (x86-64 und ARM64), macOS (Apple Silicon und Intel) und Windows (x86-64). Jedes Archiv bringt Typst, Graphviz und tree-sitter mit, sodass für Websites und Bücher nichts weiter installiert sein muss. Linux braucht glibc 2.35 oder neuer und libcurl, macOS Version 12 oder neuer. Laden Sie das Archiv für Ihr System und SHA256SUMS herunter, prüfen Sie es und installieren Sie es dann:
sha256sum -c --ignore-missing SHA256SUMS # on macOS: shasum -a 256 -c --ignore-missing SHA256SUMS
tar -xzf guidedog-linux-amd64.tar.gz
sudo install guidedog-linux-amd64/guidedog /usr/local/bin/
Installieren Sie Guidedog unter macOS aus dem offiziellen Homebrew-Tap. Homebrew wählt das Archiv für Apple Silicon oder Intel. Der Tap unterstützt auch Linux:
brew tap insanai/guidedog
brew install insanai/guidedog/guidedog
guidedog --version
Unter Windows entpacken Sie das Archiv und nehmen seinen Ordner in PATH auf; die Graphviz-DLLs und config8 bleiben neben guidedog.exe. Die Programme sind nicht codesigniert: Unter macOS entfernen Sie die Quarantäne einer im Browser heruntergeladenen Datei mit xattr -d com.apple.quarantine guidedog. Die Versionshinweise beschreiben die Grenzen jeder Plattform.
Aus dem Quellcode bauen¶
Installieren Sie Odin dev-2026-10 (tools/install-toolchain.sh odin DIR lädt und prüft es), einen C-Compiler und unter Linux die Entwicklungspakete von libcurl, expat und zlib. Bauen Sie zuerst die nativen Bibliotheken, dann Guidedog:
native/tree-sitter/build.sh
native/graphviz/build.sh
tools/release/build.sh
build/guidedog nutzt dann für PDF ein installiertes Typst 0.15.1. Um den Typst-Compiler wie die Releases einzubetten, installieren Sie Rust und Cargo und führen Sie aus:
native/typst_bridge/build.sh
tools/release/build.sh --release --typst-bridge
Unter Windows verwenden Sie Git Bash mit den C++-Werkzeugen von Visual Studio und LLVM. Für Graphviz gibt es keinen statischen Windows-Build; führen Sie daher native/graphviz/windows.sh statt build.sh aus. Es installiert die offiziellen DLLs von Graphviz 16.1.0, die tools/release/build.sh neben build/guidedog.exe kopiert. tools/release/suites.sh führt die Testsuiten aus, und RELEASING.md beschreibt den Releaseablauf.
Mit Guidedog übersetzen¶
mkdir -p docs/manual/_editions
build/guidedog build -b gettext docs/manual docs/manual/locales/templates -W
build/guidedog intl update -p docs/manual/locales/templates \
-l zh_CN -l ja -l ko -l hi -l es -l de docs/manual
build/guidedog intl stat -l zh_CN -l ja -l ko -l hi -l es -l de docs/manual
build/guidedog build -b html docs/manual docs/manual/_editions/de \
-D language=de -D 'html_extra_path=[]' -W
Übersetzen und prüfen Sie die msgstr-Werte der PO-Dateien. Guidedog extrahiert POT, führt Kataloge zusammen, zeigt den Stand und baut jede Ausgabe. Übersetzungen verfasst es nicht selbst. Befehle, Pfade, Code, API-Namen und Verweisziele bleiben unverändert. Nur Handbuch und Repositoryübersicht werden übersetzt; API und GDS bleiben Englisch. Zum Zusammenstellen aller Ausgaben und PDFs siehe die Buildanleitung.
Auf GitHub wählen Sie die README-Sprache über die Links oben. Die automatische Sprachwahl erfolgt auf der erzeugten Dokumentationswebsite.
Lesen und einbetten¶
- Handbuch: Tutorials, Themen, Aufgaben, Referenz und interne Struktur.
- API-Referenz: aus Odin-Quellcode erzeugt und im PDF-Handbuch als Anhang enthalten.
Bibliotheksleitfaden: vom Aufrufer verwaltete Workspaces, Speicher und Konvertierungsbeispiele.- Vorlagen: HTML mit Jinja und Bücher mit Typst anpassen.
GDS: nummerierte Entwurfsunterlagen und Implementierungsentscheidungen.Betaprüfung: Korrekturen, Prüfungen, Unterstützungsumfang und offene Releasebedingungen.
Guidedoc nutzt Speicher des Aufrufers und liefert strukturierte Diagnosen. Der Host verwaltet Dateien, Budgets, Caches, Veröffentlichung und native Compiler. --untrusted begrenzt Fähigkeiten, ist aber keine Prozesssandbox und begrenzt nicht sämtliche nativen Ressourcen. Die Beta richtet sich an vertrauenswürdige Dokumentationsprojekte unter macOS und Linux.
Danksagung und Lizenz¶
Erstellt von Vikrant Rathore, unterstützt von Ronak Rathore und Kanak Rathore. Beiträge über Issues und Pull Requests sind willkommen. Autorenangaben verwenden Namen oder Handles, keine persönlichen E-Mail-Adressen. Git-Identitätseinstellungen werden separat verwaltet.
Dank an Sphinx und Georg Brandl, Docutils und David Goodger, Typst, Tree-sitter und Max Brunsfeld, Graphviz sowie Ginger Bill und die Odin-Gemeinschaft.
Guidedog steht unter der GNU Affero General Public License v3.0 oder neuer (AGPL-3.0-or-later). Für andere Lizenzbedingungen wenden Sie sich an die Autoren. NOTICE beschreibt, wie Sie sie erreichen, und nennt die Komponenten Dritter, etwa die mitgelieferten Schriften, die ihre eigenen Lizenzen behalten.
Eine zusätzliche Erlaubnis gestattet, Guidedog zusammen mit Graphviz zu linken und weiterzugeben; siehe NOTICE.