Notist Book

命令与配置

Book 使用 package 的 [site]。命令行见 Notist CLI，字段和路径基准见 Notist.toml 配置。

包根就是 Notist.toml 所在目录，content 指定内容目录。build 生成站点文件；serve 提供本地预览，文件变化后自动重建，失败时保留上次可用预览。

notist build
notist serve --port 8000

预览中的错误和警告会显示在终端及浏览器诊断面板中。使用 --no-clear-screen 保留每轮终端输出。

项目的 Notist.toml 分别选择扩展和主题：

[package]
name = "my-docs"

[site]
title = "My Book"
content = "."
theme = "builtins.book"
directory_urls = true
copy_content_assets = false
exclude = ["drafts/**", "**/AGENTS.md"]

[site.extensions.builtins.book]
select = true

include 默认允许所有文档，exclude 默认为空；匹配对象相对 content，* 不跨目录，** 跨目录。SUMMARY 的 select 默认 false，只组织导航；上例显式启用章节选择。点开头的条目、target、node_modules、输出目录及主题输入不参与正文发现。

include / exclude 都使用 glob；AGENTS.md 只匹配根目录，**/AGENTS.md 匹配任意目录（包含根目录）。不使用 gitignore 的无斜杠简写或 ! 重新包含规则。无效 glob 使构建失败。

[package]
name = "my-book"

[site]
content = "."
theme = "builtins.book"
directory_urls = true
copy_content_assets = false
extensions.builtins.book = { select = true }
output = "../build/book"
include = ["**"]
exclude = ["**/AGENTS.md", "art/**/source/**"]

[[site.mounts]]
source = "../art"
path = "art"

路由与导航

directory_urls = true 时，以下源路径相对于 content：

README 的匹配区分大小写。所有已注册文档前端使用相同规则；路径段进行 URL 编码。标题不改变 URL。同一个输出路径出现多个文档时报告冲突，例如 README.not 与 README.md，或 guide.not 与 guide/README.md。

没有 SUMMARY 时，导航按目录层次与文件名自然排序，同目录的 README 排在其他页面之前。没有 README 的目录显示为无链接的分组。页面标题取第一个标题，没有标题时使用文件名；根 README 的标题还可回退到书名。

内置主题提供章节导航、面包屑、上一篇 / 下一篇、页内目录、阅读进度和代码复制，支持移动端与明暗模式。serve 在缺少根 README 时将 / 重定向到第一个页面。

SUMMARY：阅读结构

在 Vault 根目录创建 SUMMARY.not 或 SUMMARY.md，列出需要发布的章节及顺序。两种格式选择一种；SUMMARY 专用于导航，即使被 include / exclude 排除也会读取。

结构语义对齐 mdBook SUMMARY，使用 .not 的标题、列表、链接与分隔线语法：

= 目录

[首页](README.not)

= 入门

- [开始使用](guide/start.not)
  - [进阶](guide/advanced.md)

= 参考

- [参考](reference.not)
- [计划中的章节]()

---

[贡献者](contributors.not)

SUMMARY.md 使用 Markdown 语法，章节可以混合指向 .not 和 Markdown；目录发现与 collapsed 注解同样可用，例如：

# Summary

[首页](README.md)

# 入门

- [开始使用](guide/start.not)
  - [进阶](guide/advanced.md)
- [计划中的章节]()

# 归档

- @(collapsed: true)[历史记录](_logs/)

---

[贡献者](contributors.md)

章节列表使用无序列表；.not 使用减号，Markdown 支持减号、星号或加号。导航标题按用户书写的文字显示，不生成章节编号。需要编号时，直接写进链接文字或页面标题，例如：

- [1. 开始使用](guide/start.not)
  - [1.1. 进阶](guide/advanced.md)
- [附录 A：参考](reference.not)

编号作为标题文字显示，增删或移动章节时需自行调整。

支持以下结构元素：

• 文件标题：开头可写一个 = 目录，仅说明结构文件，不设置书名；省略也可。后续的一级标题作为分节标题，其他标题级别忽略。

• 前置章节：首个章节列表之前的独立链接，例如 [首页](README.not)，只在顶层显示。

• 分节标题：= 入门 为后续章节添加不可点击的视觉分隔，章节仍保持原来的层级，分节标题不进入面包屑。

• 章节条目：- [开始使用](guide/start.not)，嵌套列表声明子章节，链接文字原样显示。

• 后置章节：章节列表之后的独立链接。进入后置章节后只能继续写独立链接和分隔线。

• 草稿章节：空目标链接，例如 - [计划中的章节]()，在导航中显示为不可用链接，保留其标签，不生成页面或源文件，也不参与上一篇 / 下一篇。

• 分隔线：独占一行的至少三个减号 ---，可以放在顶层元素之前、之间或之后，在导航中显示横线。

章节链接指向相对于结构文件的源文件，可以混合 .not 与 Markdown；目标必须存在并符合 include / exclude 等发现条件。链接文字覆盖导航和面包屑标题；文字为空时使用页面标题。页面正文和上一篇 / 下一篇保留页面自身标题。

导航与面包屑严格跟随章节列表的缩进，顶层条目互为同级；首页也遵循相同规则。上一篇 / 下一篇按深度优先前序遍历实际页面，跳过分节、分隔线、草稿及无内容的章节。上例的页面顺序为：首页 → 开始使用 → 进阶 → 参考 → 贡献者。进阶页的面包屑为：开始使用 → 进阶，URL 保持 /guide/advanced/。

纯文字条目（例如 - 玩法设计）用于分组，目录链接（例如 [历史记录](_logs/)）用于自动收集页面。两者都可嵌套子章节；目录发现和折叠设置见下文。

SUMMARY 中的章节目标须为本地文档或目录。重复条目、无效目标与不支持的结构会使构建失败。

- [首页](README.not)
- 入门
  - [开始使用](guide/start.not)
- [历史记录](_logs/)

- [入门](guide/)
- @(collapsed: true)[历史记录](_logs/)

- @(collapsed: true)
  参考资料
  - [语法](syntax.not)

链接、锚点与资源

Book 将 ![描述](assets/example.png "标题")（Markdown 与 Markup 均支持）及 #embed 引用的图片渲染为 img，description 作为 alt，title 保留在外层 span。按 URL 路径扩展名识别 PNG、JPEG（jpg / jpeg）、GIF、SVG、WebP、AVIF、APNG、BMP 和 ICO，忽略大小写及 query / fragment；本地与远程图片均适用。其他资源仍显示为链接；无图片扩展名的远程 URL 也使用链接。build 与 serve 预览使用相同呈现。

本地链接按源文件位置解析，并指向对应的书籍页面；query 与 fragment 保留。资源也可通过 Path 引用。

标题自动生成锚点，重复时追加 -2、-3 等序号；也可以用 id 注解指定锚点。

正文与资源的发布范围为 Vault 及显式 mounts。缺失页面、文件或锚点的普通链接产生警告；嵌入资源缺失或超出发布范围会阻止构建。

引用的资源按书籍相对路径复制，使用的组件及辅助文件发布到 notist/modules/。notist 是生成资源的保留目录。

代码块高亮

代码块标注语言后即可在构建时生成高亮，支持 Rust、TypeScript / TSX、TOML、Dockerfile、Notist 等。未标注或未知语言按纯文本显示。rust,ignore、rust,no_run 等标签使用对应语言的高亮。

共享的 _notist/highlight.css 提供明暗配色，与页面主题同步。通过 styles 中的附加 CSS 覆盖 --notist-code-* 变量。高亮保留源码空白与末尾换行，复制按钮复制原始内容。

Tera 主题

主题支持三层定制：通过 CSS 变量调整外观，通过 styles / scripts 追加资源，通过 templates / static_dir 覆盖同名模板和静态资源。

[package]
name = "handbook"

[site]
title = "Project Handbook"
content = "."
theme = "builtins.book"
directory_urls = true
copy_content_assets = false
styles = ["styles/palette.css", "styles/content.css"]
scripts = ["scripts/reader.js"]
extensions.builtins.book = {}

附加路径相对 content，也可通过已授权挂载的真实路径选择文件。CSS 在内置样式后按声明顺序加载，JS 在 book.js 后以 defer 加载。static_dir 覆盖主题同名资源；不会自动追踪 CSS url()、JS import 或组件参数中的路径。

轻量定制可只写一个样式表，例如 styles/palette.css：

:root {
  --accent: #6d28d9;
  --font-reading: system-ui, sans-serif;
  --reading-width: 780px;
  --navigation-width: 300px;
}
:root[data-theme="dark"] { --accent: #c4b5fd; }

配色变量还包括 --bg、--fg、--muted、--line、--code、--surface、--selection；--font-ui 与 --font-code 分别控制界面和代码字体。默认明暗配色基于系统偏好；覆写深色配色时，可结合 prefers-color-scheme 与 data-theme 显式选择规则。

--navigation-width 设置侧栏默认宽度，--book-width 设置整体布局的最大宽度（默认 1440px）。读者保存的侧栏宽度优先于主题默认值；重置后重新使用 --navigation-width。

自定义 page.tera 时，在 head 中保留主题初始化代码，并在目录节点后 include navigation-script，以恢复阅读位置与侧栏设置。

模板引擎使用 Tera 2，模板名是 templates 目录相对路径去掉 .tera。局部模板通过 include 引用，也可通过 extends / block 组织布局。内置 navigation 定义 book_navigation(node, current, ancestors) 组件，递归调用时显式传递当前输出路径和祖先 ID。Tera 不允许循环 include。

默认资源包含独立的 status.css，为 draft、staged 与 outdate 注解提供样式。主题可通过同名资源覆盖，规则见 HTML 内容状态。

theme/
├── templates/
│   ├── page.tera
│   └── title.tera
└── static/
    ├── book.css
    └── extra.css

Book 扩展的数据位于 site.data.book；普通页面上下文沿用 SSG，不增加 Book 专用顶层字段：

beforecompile 解析 SUMMARY 并将章节结构保存在本次构建的扩展实例中；beforetemplate 根据最终 Pages 生成完整的 site.data.book，不通过模板 data 传递中间状态。

导航树只存一份，current 不作为当前页状态使用；主题通过 node.output 与 page.route.output 比较选中状态，通过 expanded 或节点 ID 是否位于当前 ancestors 中决定展开。导航 URL 相对输出根，可用 url(path=node.url, relative_to=page.route.output) 转成当前页相对 URL。breadcrumbs 和相邻页 URL 已相对当前页面。

attrs 来自目标文档根节点的模块注解（@!），不包含局部标题或正文注解；无目标文档的目录节点使用空对象。page、navigation 和 breadcrumbs 使用相同投影：字符串、布尔和数值为 JSON 标量，数组和字典递归转换，Some 展开，Unit、None 与非有限浮点数为 null。这是主题呈现数据，不使用组件的 typed JSON 协议；不参与章节排序或路由。模板默认转义输出，访问可选字段前使用 if 检查，例如在 navigation-label.tera 中用 {% if node.attrs.subtitle %}<small>{{node.attrs.subtitle}}</small>{% endif %}。

<!doctype html>
<html><head><meta charset="utf-8"><title>{{page.title}} · {{site.title}}</title>
{% for style in assets.styles %}<link rel="stylesheet" href="{{style}}">{% endfor %}
{% for script in assets.scripts %}<script src="{{script}}" defer></script>{% endfor %}
</head><body>
{% include 'title' %}
<article>{{page.html | safe}}</article>
{% if assets.components %}<script type="module" src="{{assets.components}}"></script>{% endif %}
</body></html>

title.tera 可使用 {{page.title}}。普通插值转义 HTML，渲染后的 page.html 使用 safe 过滤器。未定义字段与模板语法错误使构建失败。

Library 接口

let mut vault = notist::Vault::new(resources);
let mut config = notist_ssg::SiteConfig::default();
config.theme = Some("builtins.book".into());
config.extensions.builtins.book = Some(Default::default());
let output = notist_ssg::Builder::default().build(&mut vault, &config)?;
// output.data.book 包含导航与阅读顺序，output.pages 保持站点页面顺序。
// output.files 保存相对输出路径与完整字节，宿主负责发布。

serve 使用与 build 相同的参数和返回类型，在内存中构建并将可恢复的 Code 错误呈现为诊断节点；HTTP 服务与文件监听由 CLI 提供。

Book 扩展位于 notistssg::builtins::book，通过 SiteConfig 启用，或通过 Builder.withextension 注册。files 保存页面与资源，data 保存扩展数据，warnings 保存链接警告，diagnostics 保存预览中可恢复的内容错误。

GitHub Pages

仓库的 Documentation workflow 使用 flake.lock 固定开发环境，先构建 Grammar WASM，再在仓库根运行 notist build，上传 notist-output/notist 并部署。根 Notist.toml 同时声明 workspace、包身份与发布 docs 内容的 site；docs/README.not 发布到 /。示例包拥有独立发布目录，modules/ 提供模块与组件资源。

push 到 main 与手动运行会构建并部署；pull request 只构建并上传产物。Pages 的发布来源设置为 GitHub Actions，部署使用 github-pages environment。站点内部链接与资源使用相对 URL，可直接发布在仓库子路径下。