# Guidedog

[English](README.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [हिन्दी](README.hi.md) · [Español](README.es.md) · [Deutsch](README.de.md)

**一度書く。明快に伝える。Web と紙に届ける。**

Guidedog は reStructuredText と Markdown から HTML 文書サイトと PDF の本を作ります。Odin で実装され、変換エンジンは **Guidedoc** と呼ばれます。PDF は Typst で組版します。Python 環境や LaTeX は不要です。

執筆の流れは Sphinx を参考にしています。ただし Guidedog は独立したシステムです。設定は宣言的な TOML、API 抽出は静的解析で行い、Python の設定や拡張を実行しません。Sphinx との完全互換は目標ではありません。

## プロジェクトを始める

```sh
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 には章、相互参照、図、索引、言語に応じた組版があります。

既定は明るいテーマで、暗いテーマやシステム設定も選べます。マニュアルの入口とリポジトリ概要ではブラウザーの言語に合わせます。保存した選択が優先され、特定の版や章への直接リンクは尊重されます。

```sh
guidedog convert notes.md --to pdf --output notes.pdf
guidedog clean docs
guidedog migrate conf.py
```

## インストール

各[リリース](https://github.com/insanai/guidedog/releases)には Linux（x86-64 と ARM64）、macOS（Apple シリコンと Intel）、Windows（x86-64）向けのアーカイブがあります。どのアーカイブにも Typst、Graphviz、tree-sitter が入っているので、サイトや本のビルドにほかのものは要りません。Linux には glibc 2.35 以降と libcurl、macOS にはバージョン 12 以降が必要です。お使いのシステム向けのアーカイブと `SHA256SUMS` をダウンロードし、確認してからインストールします。

```sh
sha256sum -c --ignore-missing SHA256SUMS      # 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](https://github.com/insanai/homebrew-guidedog) からインストールします。Homebrew が Apple シリコンまたは Intel 用のアーカイブを選びます。この tap は Linux にも対応しています。

```sh
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 をビルドします。

```sh
native/tree-sitter/build.sh
native/graphviz/build.sh
tools/release/build.sh
```

できあがった `build/guidedog` は、PDF の生成にインストール済みの Typst 0.15.1 を使います。リリース版と同じように Typst コンパイラーを組み込むには、Rust と Cargo を用意して次を実行します。

```sh
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](RELEASING.md) にあります。

## Guidedog で翻訳する

```sh
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 のまとめ方は[ビルド手順](docs/manual/README.md)を参照してください。

GitHub では上のリンクから README の言語を選びます。言語の自動選択は生成した文書サイトで行います。

## 読む・組み込む

- [マニュアル](docs/manual/index.rst): チュートリアル、解説、作業手順、リファレンス、内部構造。
- [API リファレンス](docs/api/index.rst): Odin ソースから生成し、マニュアル PDF の付録にも含めます。
- [ライブラリガイド](lib/README.md): 呼び出し元が所有するワークスペース、メモリ、変換例。
- [テンプレート](docs/manual/templates.rst): Jinja で HTML、Typst で本を調整します。
- [GDS](docs/gds/README.md): 番号付きの設計記録と実装上の判断。
- [ベータレビュー](docs/manual/evidence/beta-review-20261011.md): 修正、検証、対応範囲、公開前の残課題。

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 以降](LICENSE)（AGPL-3.0-or-later）で公開しています。別のライセンス条件をご希望の場合は、作者にご連絡ください。連絡方法と、同梱フォントなど独自のライセンスが適用される第三者コンポーネントの一覧は [NOTICE](NOTICE) にあります。 追加の許可により、Guidedog を Graphviz とリンクして配布できます。詳しくは [NOTICE](NOTICE) をご覧ください。