Guidedog¶
写一次，讲清楚，发布到网页，也印在纸上。
Guidedog 用同一组 reStructuredText 或 Markdown 文件生成文档网站和 PDF 图书。文字只需写一次，两个版本由 Guidedog 保持一致。
输入一个纯文本文件，Guidedog 用它生成一个网页和一页书。
它做什么¶
- 网站。 页面带有导航、搜索、代码高亮以及浅色和深色主题，由可以随意修改的 Jinja 模板生成。
- PDF 图书。 章节、交叉引用、图、表、脚注和索引，由 Typst 按各语言的规则排版。
- reStructuredText 与 Markdown。 指令、角色、目录树和交叉引用的用法与 Sphinx 用户熟悉的一致，MyST Markdown 也可以放在一起使用。
- 翻译。 用 gettext 目录把项目译成其他语言。中文、日文、韩文和印地文在屏幕上和纸面上都能正确排版。
- 图表、公式与 API 页面。 Graphviz 图表、LaTeX 公式，以及从源代码读取的 Odin API 参考。
- 清楚的错误信息。 信息说明出了什么问题、在哪里、怎样修复。构建失败时，上一次成功的网站保持不变。
一个程序¶
Guidedog 是一个单独的可执行文件。不需要 Python 环境，不需要安装 LaTeX，也不需要另装主题或扩展包。配置是一个 TOML 文件，模板是项目里可以直接编辑的普通文件。
有些东西仍然来自外部。Guidedog 可以在构建时内置 Typst 和 Graphviz；未内置时，它使用系统中安装的 typst 和 Graphviz 程序。在 Linux 和 macOS 上，它还会用到几个系统库，例如 libcurl。
写一次，看两种结果¶
左边是 reStructuredText，右边是 Guidedog 在本页上用它生成的结果。PDF 构建器会把同样的内容排成书页。
.. note::
Guidedog 只读一次你的文字。
*同一组* 文件既成为 **网站**
也成为 **图书**：
.. list-table::
:header-rows: 1
* - 构建器
- 结果
* - ``html``
- 网站
* - ``pdf``
- PDF 图书
同一组 文件既成为 网站 也成为 图书：
| 构建器 | 结果 |
|---|---|
html |
网站 |
pdf |
PDF 图书 |
PDF 版手册 就是纸面效果的一个例子。它和手册网站来自同一组文件。
开始使用¶
从 最新发布版本 下载适合你系统的压缩包，把 guidedog 放到 PATH 中，然后创建一个项目：
guidedog quickstart docs
guidedog build html docs
guidedog build pdf docs
guidedog serve docs
quickstart 会写出 conf.toml、index.rst 和可以编辑的模板。serve 会在你写作时重新构建网站。 教程 带你完成第一个项目。要从源代码构建 Guidedog，请安装 Odin，并按照 仓库中的说明 操作。
设计讨论¶
Guidedog 的设计决定都写成了编号的讨论记录：问题、备选方案、决定和依据。每一篇都可以在网页上阅读，也可以下载 PDF。