# 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)

**写一份源码，讲清楚道理，发布到网页与纸上。**

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` 使用已安装的 Typst 0.15.1 生成 PDF。若要像发布版本那样内置 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 静态构建，因此运行 `native/graphviz/windows.sh` 代替 `build.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)：编号的设计记录和实现决策。
- [Beta 评审](docs/manual/evidence/beta-review-20261011.md)：修复、验证、支持范围和发布前的剩余事项。

Guidedoc 使用调用方提供的存储，返回结构化诊断。宿主管理文件、预算、缓存、发布和原生编译器。`--untrusted` 只限制能力，不是进程沙箱，也不限制全部原生资源消耗。Beta 面向 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 通用公共许可证 3.0 或更高版本](LICENSE)（AGPL-3.0-or-later）发布。如需其他许可条款，请联系作者。[NOTICE](NOTICE) 说明了联系方式，并列出保留各自许可证的第三方组件，例如捆绑字体。 附加许可允许将 Guidedog 与 Graphviz 链接并一同分发，详见 [NOTICE](NOTICE)。