主题目录与继承

主题根目录由 bookx.yml 的 theme.dir 指定，默认是 themes。theme.name 使用该根目录下的文件夹名称；清单中的 name 是给人阅读的展示名称。

最小继承主题

创建以下两个文件：

themes/my-theme/
├── theme.yml
└── assets/
    └── style.css

theme.yml：

name: My Theme
version: 1
description: 基于 Paper 的自定义阅读主题
extends: paper
giscus_theme: light
bundle:
  js: [main.js, archive.js, docs-menu.js, toc.js]
  css: [style.css, reading.css]

assets/style.css：

@import url("./base.css");

:root {
  --accent: #4d7778;
}

.page-heading h1 {
  letter-spacing: -0.02em;
}

base.css、reading.css 和上述脚本可从 Paper 继承，不必复制。这个例子只修改样式，没有声明外观设置面板。

再修改站点配置：

theme:
  name: my-theme
  dir: themes

运行 bookx validate 和 bookx build 后预览。工作台只扫描主题根目录的直接子目录，清单必须可解析且有 name、description，主题才会出现在选择列表里。

三类文件

未覆盖的布局、局部模板和资源继续使用父主题版本。继承可以有多层，但不能形成循环；同名文件以最靠近当前子主题的版本为准。

覆盖模板是替换整个文件，不是对父文件做文本补丁。建议先复制对应文件，再只修改需要调整的部分。覆盖 CSS 入口后也要保留必要的基础导入。

页面入口

当前页面使用的 layout 包括：

• 首页与博客：home、list、post。
• 分类和标签：taxonomy-index，分类／标签详情复用 list。
• 文档：docs-index、doc。
• 附属页面：archive、search、projects、friends、404，旧链接跳转使用 redirect。

文件名以 .html 结尾，内容定义 layout 模板。继承主题只需覆盖有差异的文件；完全独立的主题需要覆盖站点会生成的所有页面入口。是否生成文档、项目和好友页由内容与配置决定，导航应使用对应的启用状态。

接入站点外观设置

清单未声明 appearance 时，不会自动拥有内置主题的外观面板。若需要配色预设，可参考 Paper 的 appearance.presets 结构，并显式声明 bundle.css；缺少 CSS 合并入口会导致校验失败。

外观配置会作用于共享的布局类名和 CSS 变量。自行重做结构时，应确认资料位置、文章列数与分区颜色确实反映到页面上，不能只显示一组不起作用的设置。

bundle 同样不自动继承。它的列表是完整入口列表，具体规则见资源合并与验证。