Guidedog¶
English · 简体中文 · 日本語 · 한국어 · हिन्दी · Español · Deutsch
一度書く。明快に伝える。Web と紙に届ける。
Guidedog は reStructuredText と Markdown から HTML 文書サイトと PDF の本を作ります。Odin で実装され、変換エンジンは Guidedoc と呼ばれます。PDF は Typst で組版します。Python 環境や LaTeX は不要です。
執筆の流れは Sphinx を参考にしています。ただし Guidedog は独立したシステムです。設定は宣言的な TOML、API 抽出は静的解析で行い、Python の設定や拡張を実行しません。Sphinx との完全互換は目標ではありません。
プロジェクトを始める¶
guidedog quickstart docs
guidedog build html docs
guidedog build pdf docs
guidedog serve docs
プロジェクトには conf.toml、index.rst、_templates/layout.html、_templates/book.typ、_static/ があります。テンプレートは普通の編集可能なファイルです。HTML にはナビゲーション、検索、コードの強調、図、数式があり、PDF には章、相互参照、図、索引、言語に応じた組版があります。
既定は明るいテーマで、暗いテーマやシステム設定も選べます。マニュアルの入口とリポジトリ概要ではブラウザーの言語に合わせます。保存した選択が優先され、特定の版や章への直接リンクは尊重されます。
guidedog convert notes.md --to pdf --output notes.pdf
guidedog clean docs
guidedog migrate conf.py
インストール¶
各リリースには Linux（x86-64 と ARM64）、macOS（Apple シリコンと Intel）、Windows（x86-64）向けのアーカイブがあります。どのアーカイブにも Typst、Graphviz、tree-sitter が入っているので、サイトや本のビルドにほかのものは要りません。Linux には glibc 2.35 以降と libcurl、macOS にはバージョン 12 以降が必要です。お使いのシステム向けのアーカイブと SHA256SUMS をダウンロードし、確認してからインストールします。
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/
macOS では、公式の Guidedog Homebrew tap からインストールします。Homebrew が Apple シリコンまたは Intel 用のアーカイブを選びます。この tap は Linux にも対応しています。
brew tap insanai/guidedog
brew install insanai/guidedog/guidedog
guidedog --version
Windows ではアーカイブを展開し、そのフォルダーを PATH に加えます。Graphviz の DLL と config8 は guidedog.exe と同じ場所に置いたままにします。プログラムにはコード署名がありません。macOS でブラウザーからダウンロードした場合は、xattr -d com.apple.quarantine guidedog で隔離属性を外してください。各プラットフォームの制限はリリースノートに書いてあります。
ソースからビルドする¶
Odin dev-2026-10（tools/install-toolchain.sh odin DIR で取得と検証ができます）、C コンパイラー、Linux では libcurl、expat、zlib の開発パッケージを用意します。ネイティブライブラリーをビルドしてから Guidedog をビルドします。
native/tree-sitter/build.sh
native/graphviz/build.sh
tools/release/build.sh
できあがった build/guidedog は、PDF の生成にインストール済みの Typst 0.15.1 を使います。リリース版と同じように Typst コンパイラーを組み込むには、Rust と Cargo を用意して次を実行します。
native/typst_bridge/build.sh
tools/release/build.sh --release --typst-bridge
Windows では Git Bash と、Visual Studio の C++ ツール、LLVM を使います。Graphviz には Windows 向けの静的ビルドがないため、build.sh の代わりに native/graphviz/windows.sh を実行します。これは公式の Graphviz 16.1.0 の DLL をインストールし、tools/release/build.sh がそれを build/guidedog.exe の隣にコピーします。tools/release/suites.sh でテストスイートを実行できます。リリースの手順は RELEASING.md にあります。
Guidedog で翻訳する¶
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
PO ファイルの msgstr を翻訳し、内容を確認します。Guidedog は POT 抽出、カタログのマージ、進捗表示、各版のビルドを行いますが、翻訳文を自動で作りません。コマンド、パス、コード、API 名、参照先は変えません。翻訳するのはマニュアルとリポジトリ概要のみで、API と GDS は英語のままです。各版と PDF のまとめ方はビルド手順を参照してください。
GitHub では上のリンクから README の言語を選びます。言語の自動選択は生成した文書サイトで行います。
読む・組み込む¶
- マニュアル: チュートリアル、解説、作業手順、リファレンス、内部構造。
- API リファレンス: Odin ソースから生成し、マニュアル PDF の付録にも含めます。
ライブラリガイド: 呼び出し元が所有するワークスペース、メモリ、変換例。- テンプレート: Jinja で HTML、Typst で本を調整します。
GDS: 番号付きの設計記録と実装上の判断。ベータレビュー: 修正、検証、対応範囲、公開前の残課題。
Guidedoc は呼び出し元のストレージを使い、構造化された診断を返します。ホストがファイル、予算、キャッシュ、公開、ネイティブコンパイラーを管理します。--untrusted は機能を制限しますが、プロセスのサンドボックスでも、すべてのネイティブ資源の上限でもありません。ベータ版の対象は macOS と Linux の信頼できる文書プロジェクトです。
謝辞とライセンス¶
Vikrant Rathore が制作し、Ronak Rathore と Kanak Rathore が開発を支援しました。Issue や Pull Request による貢献を歓迎します。文書の著者表記には名前やハンドルを使い、個人のメールアドレスは掲載しません。Git の識別情報は別に管理します。
Sphinx と Georg Brandl、Docutils と David Goodger、Typst、Tree-sitter と Max Brunsfeld、Graphviz、Ginger Bill と Odin コミュニティに感謝します。
Guidedog は GNU Affero General Public License v3.0 以降（AGPL-3.0-or-later）で公開しています。別のライセンス条件をご希望の場合は、作者にご連絡ください。連絡方法と、同梱フォントなど独自のライセンスが適用される第三者コンポーネントの一覧は NOTICE にあります。
追加の許可により、Guidedog を Graphviz とリンクして配布できます。詳しくは NOTICE をご覧ください。