/ Book 模式 / 组织章节 (SUMMARY.md)

SUMMARY.md 是站点的目录结构文件,默认位于根目录。它定义了导航栏、面包屑、以及“上一页/下一页”链接的顺序与层级。

SUMMARY.md 使用 Markdown 列表来描述章节结构,以下是本书的完整结构:

# Summary

[介绍](./introduce.md)

---

## 指南

- [快速开始](./starting.md)

- [Book 模式](./book-mode/index.md)
  - [配置 (sena.toml)](./book-mode/configuration.md)
  - [组织章节 (SUMMARY.md)](./book-mode/summary-file.md)
  - [元数据](./book-mode/frontmatter.md)
  - [扩展配置](./book-mode/extensions.md)
  - [功能预设](./book-mode/features.md)
  - [页面定制](./book-mode/pages.md)

- [Site 模式](./site-mode/index.md)
  - [开始](./site-mode/starting.md)
  - [Rules, Handlers 和 Steps](./site-mode/rules-handlers-steps.md)
  - [组合 Steps](./site-mode/composing-steps.md)
  - [输出格式](./site-mode/output-formats.md)

- [高级](./advance/index.md)
  - [模板引擎](./advance/template.md)
  - [Glob 匹配](./advance/glob.md)
  - [多样化的插件](./advance/plugins/index.md)
    - [外部插件协议](./advance/plugins/protocol.md)
    - [Web Components](./advance/plugins/web-components.md)
    - [Moonbit 模块](./advance/plugins/moonbit-modules.md)

## 参考

- [Markdown 演示](./references/markdown.md)
- [CLI 参考](./references/cli.md)
- [Api 参考](./references/api.md)

---

[插件枢纽](./plugins.md)
[贡献](./contributing.md)
[Changelog](./changelog.md)

## English

[Introduction](./en/introduce.md)

---

### Guide

- [Quick Start](./en/starting.md)

- [Book Mode](./en/book-mode/index.md)
  - [Configuration (sena.toml)](./en/book-mode/configuration.md)
  - [Structuring Chapters (SUMMARY.md)](./en/book-mode/summary-file.md)
  - [Frontmatter Metadata](./en/book-mode/frontmatter.md)
  - [Extension Configuration](./en/book-mode/extensions.md)
  - [Feature Presets](./en/book-mode/features.md)
  - [Page Customization](./en/book-mode/pages.md)

- [Site Mode](./en/site-mode/index.md)
  - [Starting](./en/site-mode/starting.md)
  - [Rules, Handlers and Steps](./en/site-mode/rules-handlers-steps.md)
  - [Composing Steps](./en/site-mode/composing-steps.md)
  - [Output Formats](./en/site-mode/output-formats.md)

- [Advanced](./en/advance/index.md)
  - [Template Engine](./en/advance/template.md)
  - [Glob Matching](./en/advance/glob.md)
  - [Diverse Plugins](./en/advance/plugins/index.md)
    - [External Plugin Protocol](./en/advance/plugins/protocol.md)
    - [Web Components](./en/advance/plugins/web-components.md)
    - [MoonBit Modules](./en/advance/plugins/moonbit-modules.md)

### References

- [Markdown Showcase](./en/references/markdown.md)
- [CLI Reference](./en/references/cli.md)
- [API Reference](./en/references/api.md)

---

[Plugins Hub](./en/plugins.md)
[Contributing](./en/contributing.md)
[Changelog](./en/changelog.md)

其中:

  • 前言与后记(Prefix & Suffix Chapters):未放入列表中的裸链接(如 [介绍](./introduce.md) 或文末的 [贡献](./contributing.md))不会带有数字编号,适合作为书籍的前置引导、补充说明或附录。

  • 分组标题(Part Title):标题(如 # 指南、## 参考)会被解析为分组标签,用于在导航侧边栏中对章节进行视觉分组,本身不对应具体页面。

  • 编号章节(Numbered Chapters):使用无序列表语法 - [标题](路径) 组织主体章节。在各个 Part 分组内部,顶层章节会自动且独立地从 1 开始按顺序编号,不同分组互不干扰。

  • 多级嵌套:无序列表可以通过缩进(2 个或 4 个空格)表示嵌套子章节,子章节会自动继承父级编号(例如 2.1、2.2、2.2.1)。

  • 分隔线(Separator):使用 ---(三个连字符)可以在侧边栏插入水平分割线。分隔线和前后记章节严格按照你在 SUMMARY.md 中书写的物理顺序呈现,完美支持单语言与多语言分区的复杂混合结构。

SUMMARY.md 只负责定义导航结构(面包屑、上一页/下一页链接、以及自动生成的目录树),它并不控制构建时会处理哪些文件。

MoPress 在构建时会直接通过 glob 规则扫描源目录下所有的 *.md 与 *.markdown 文件,并将它们各自渲染为对应的 HTML 页面——这个过程与 SUMMARY.md 完全独立。也就是说:

  • 一个文件即使没有出现在 SUMMARY.md 中,只要它位于源目录下并以 .md、.markdown 结尾,依然会被构建为页面(只是不会出现在导航结构里,也不会有正确的面包屑、上一页下一页信息)。

  • 反过来,如果 SUMMARY.md 中引用了某个实际不存在的文件路径,构建时读取该文件会失败。

如果你希望某个页面既能被正常访问、又不出现在主导航中(如落地页、法律声明页等),可以不将其写入 SUMMARY.md;但请注意,此时该页面的面包屑与上一页、下一页信息将无法被正确计算。