Guidedog / 文档 0.2.0

第一个项目¶

目标很小：在浏览器中显示一页，并将同一页输出为 PDF。先准备 Guidedog。PDF 可使用内置编译器，或安装 Typst 0.15.1 及以上版本。见构建并安装 Guidedog。

在 macOS 上，运行 brew install insanai/guidedog/guidedog 安装发行版。此命令会添加官方 tap，安装包已包含 PDF 编译器。

创建项目¶

在尚不存在 notes 的目录中运行：

guidedog quickstart notes -q -p "Field Notes" -a "Your name" -v 1.0

Guidedog 写入配置、首份 RST 文档和可编辑模板，并为图片、音频、视频创建目录。它拒绝覆盖已有项目。

notes/
  conf.toml
  index.rst
  _templates/
    layout.html
    book.typ
  _static/
    guidedog.css
    guidedog.js
  assets/
    images/
    audio/
    video/
  _build/

RST 文件保存正文，模板控制呈现。quickstart 会将 _templates/layout.html 和 _templates/book.typ 直接写入项目，而不是藏在外部主题或包缓存中。随时可查看和修改。

编写第一个页面¶

将 notes/index.rst 替换为：

Field Notes
===========

A useful explanation begins with a small example.

Measuring a square
------------------

If the side has length :math:`s`, its area is :math:`s^2`.

.. math::

   A = s^2

.. note::

   State the units before comparing measurements.

构建与检查¶

guidedog build html notes -W
guidedog build pdf notes -W

打开 notes/_build/html/index.html 和 notes/_build/pdf 中的 PDF。-W 使警告导致构建失败，应保留在文档检查中。HTML 包含导航和正文；PDF 增加书籍的页眉、页脚等版式。公式按各目标格式排版，设置详见数学与证明。

修改内容¶

guidedog serve notes

打开命令打印的地址，编辑源文件并保存，然后刷新浏览器。提供 HTML 前，Guidedog 检查源文件修改时间，若有更新则重建。它不会主动推送浏览器刷新。用 Ctrl+C 停止服务器。

不修改任何内容，再次构建。未变化的文档会复用，无需重新读取每一页来证明输出仍有效。接着阅读制作一本小书。