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)
其中:
在第一个无序列表(即
- [xxx](...))出现前的所有链接视为前言章节(Prefix Chapters),通常用于放置书籍的非核心内容、提示等,诸如实例中的[介绍](./introduction.md)。在第一个无序列表之后的出现所有非无序列表链接被视为后记章节(Suffix Chapters),通常用于放置书籍的补充、声明内容等,诸如实例中的
[常见问题](./faq.md)。顶层的一级标题(
# 使用指南)会被解析为分组标题(Part Title),用于在导航中对多个章节进行分组,本身不对应任何页面。无序列表项
- [标题](路径)视为正文,是编号章节(Numbered Chapters),会在侧边栏显示自动生成的章节编号。无序列表可以通过缩进表示嵌套子章节。
使用
---(三个连字符)可以插入一条分隔线(Separator),用于在视觉上分隔不同的章节组。
SUMMARY.md 只负责定义导航结构(面包屑、上一页/下一页链接、以及自动生成的目录树),它并不控制构建时会处理哪些文件。
MoPress 在构建时会直接通过 glob 规则扫描源目录下所有的 *.md 与 *.markdown 文件,并将它们各自渲染为对应的 HTML 页面——这个过程与 SUMMARY.md 完全独立。也就是说:
一个文件即使没有出现在
SUMMARY.md中,只要它位于源目录下并以.md、.markdown结尾,依然会被构建为页面(只是不会出现在导航结构里,也不会有正确的面包屑、上一页下一页信息)。反过来,如果
SUMMARY.md中引用了某个实际不存在的文件路径,构建时读取该文件会失败。
如果你希望某个页面既能被正常访问、又不出现在主导航中(如落地页、法律声明页等),可以不将其写入 SUMMARY.md;但请注意,此时该页面的面包屑与上一页、下一页信息将无法被正确计算。