bookx主题设计指南
从最小继承主题到模板数据、资源合并、响应式设计与构建验收。
BookX 主题负责把编译器整理好的内容显示为网页。Markdown 解析、稳定内容 ID、文档关系、排序与路由由编译核心负责；主题维护 HTML、CSS 和浏览器交互。
这份指南从一个继承 Paper 的最小主题开始，再介绍页面字段、资源合并和视觉验收。修改主题不需要改变文章或文档格式。
先选合适的修改范围
| 目标 | 推荐入口 |
|---|---|
| 调整现有主题颜色、圆角、透明度或文章列数 | 工作台中的站点主题外观设置 |
| 保留阅读布局，换字体与局部样式 | 创建继承主题，覆盖 CSS |
| 修改首页或某一种页面结构 | 覆盖对应 layout 或 partial |
| 重新设计全部页面 | 自行提供完整模板，同时保留内容与路由协议 |
工作台自身的配色与公开站点主题彼此独立。这里讨论的是构建到 dist/ 的站点主题，不是 internal/studio/src/ 中的管理界面。
阅读顺序
- 主题目录与继承：建立最小主题，理解文件覆盖规则。
- 模板与页面数据：使用站点、内容、分页、文档树和归档字段。
- 资源合并与验证：声明脚本入口，处理子路径并检查构建产物。
- 视觉语言：统一阅读布局、配色、移动端和交互反馈。
内置主题
| 主题 ID | 风格 |
|---|---|
paper | Paper 阅读布局，提供纸白、雾青、夜幕、清透四种配色 |
mono | 黑白出版物风格 |
blush | 樱花粉与莓色 |
collage | 拼贴、贴纸与手工层次 |
cyber | 黑黄科幻界面 |
terminal | 深色终端、青色强调与细网格 |
内置子主题通过继承复用基础布局和交互，各自覆盖视觉差异。开发时优先在独立自定义目录中修改，避免把站点个性化和内置主题升级混在一起。
主题必须守住的边界
- 使用模板提供的 URL，不根据标题重新生成 slug，也不硬编码部署子路径。
- 使用传入的可见内容，不从源文件重新读取草稿、私有或仅本地内容。
- 每页有明确的主内容区域和一个一级标题，正文保留语义结构。
- 图片和代码要能在窄屏阅读；动画应尊重减少动画设置。
- 先验证根域名，再验证 GitHub Pages 子路径；修改源文件后重新构建，不直接编辑生成目录。
站点使用和内容编写方式见BookX 使用手册。
讨论这篇内容
评论由 GitHub Discussions 提供 · 打开讨论仓库