Guidedog¶
English · 简体中文 · 日本語 · 한국어 · हिन्दी · Español · Deutsch
写一份源码，讲清楚道理，发布到网页与纸上。
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 使用已安装的 Typst 0.15.1 生成 PDF。若要像发布版本那样内置 Typst 编译器，安装 Rust 和 Cargo 后运行：
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 介绍发布流程。
用 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：编号的设计记录和实现决策。Beta 评审：修复、验证、支持范围和发布前的剩余事项。
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 或更高版本（AGPL-3.0-or-later）发布。如需其他许可条款，请联系作者。NOTICE 说明了联系方式，并列出保留各自许可证的第三方组件，例如捆绑字体。
附加许可允许将 Guidedog 与 Graphviz 链接并一同分发，详见 NOTICE。