资源合并与验证

主题源文件保存在 assets/，构建时复制并按清单生成合并资源。最终用户使用主题不需要安装 Node.js，合并工具随 BookX 一起运行。

显式声明完整入口

继承 Paper 并保留共享交互时：

bundle:
  js: [main.js, archive.js, docs-menu.js, toc.js]
  css: [style.css, reading.css]

入口相对当前主题的 assets/，先按父子继承规则解析同名文件，再按声明顺序合并。列表是完整入口列表，不会自动追加父主题脚本；bundle 本身也不自动继承。

如果继承 Terminal 并保留首页时钟与头像交互，JS 入口还需要 clock.js、portrait.js。新增自己的脚本时，把实际存在的文件追加到列表。不要同时在模板里再次加载已进入合并文件的脚本。

可以只合并 CSS 或 JS。未声明的一类仍按原始模板加载；旧自定义主题完全不声明 bundle 时保留原加载行为。

页头引用

构建后合并文件使用带内容哈希的名称。继承内置 head 就会自动引用它们；自行覆盖页头时，使用编译器提供的 URL：

{{ if .Site.BundleCSSURL }}
<link rel="stylesheet" href="{{ .Site.BundleCSSURL }}">
{{ else }}
<link rel="stylesheet" href="{{ .Site.AssetsURL }}style.css">
<link rel="stylesheet" href="{{ .Site.AssetsURL }}reading.css">
{{ end }}
{{ if .Site.BundleJSURL }}
<script defer src="{{ .Site.BundleJSURL }}"></script>
{{ end }}

这是引用片段；若支持未合并的 JS，还要保留所需的独立脚本分支。最小主题示例已经声明 JS 合并入口，可直接继承完整页头。

CSS 依赖和图片路径

本地 @import 会展开，媒体条件和层叠规则会保留。图片、字体等相对 URL 会按合并文件的位置改写，依赖必须位于主题 assets/ 内。

CSS 中优先使用相对资源地址，例如 url("./images/pattern.svg")，并在同目录下提供文件。外部地址不会自动下载。硬编码 /assets/... 会从域名根开始，不能自动适应项目子路径。

CSS 不压缩、不混淆类名；合并后的格式可能因解析重写变化，原样式文件仍保留。不要手动修改 dist/assets/theme/ 中的资源来修复源文件问题。

JavaScript 的约定

参与合并的 .js、.mjs 可以通过明确相对文件名导入本地模块，使用 import、export 共享值。独立脚本需要调用的接口应显式暴露到 window，不要依赖其他文件的局部变量。

脚本在 DOM 解析后运行，找不到对应元素时应直接退出。避免依赖 document.currentScript、import.meta.url 或原 <script async> 的执行时机。远程模块、裸包名和 JS 中直接导入 CSS 不属于该入口协议；第三方脚本继续独立加载。

HTML 和 JS 会压缩，JS 局部变量会缩名。不要依赖函数名称反射，也不要把密钥、口令或令牌放进任何前端文件。动态展示标题、分类等普通文本时使用 textContent，保留转义边界。

本地开发与构建

在工作区运行：

bookx validate
bookx build
bookx serve

需要监听变化时，在另一个终端运行 bookx watch -drafts=false。watch 负责重新构建，serve 负责访问；源文件变化后刷新页面。验证命令会检查内容、资源和生成页面，失败时按报错中的源文件或资源路径修正。

根域名与子路径都要验证

先用 base_path: "" 构建，再在临时工作区配置 base_path: /preview 构建。第二次访问地址应包含 /preview/，重点检查导航、正文图片、搜索和归档 JSON，不能只检查首页颜色。

每轮至少检查：

首页，文章列表，文章详情，分类与标签。
文档合集首页、多级目录、关闭首页的子目录和面包屑。
归档首屏、跨批次同年合并、全部完成后分页隐藏，以及静态第 2 页。
桌面、平板和手机下的长标题、代码块、表格和图片。
键盘焦点、目录抽屉、图片弹窗、减少动画，以及无 JS 时的内容入口。

没有项目、好友或公开文档时，相关导航不应指向不存在的页面。修改后应检查最终合并脚本，不能只在源码单文件环境中测试交互。

常见构建问题

现象	优先检查
主题没有出现在工作台	是否位于主题根目录直接子级，清单是否有名称与描述
找不到布局或 partial	覆盖文件是否定义了正确模板，父主题是否存在
CSS 或模块导入失败	相对路径、文件大小写、依赖是否越过 assets 边界
子路径下图片或搜索失败	是否硬编码根路径或重复追加部署子路径
归档只能看到首批内容	JS 列表是否包含 `archive.js`，共享模板标记是否保留
动作执行两次	原始脚本是否与合并文件重复加载
修改样式没有变化	是否重新构建，页面是否引用新的内容哈希文件

资源解析、合并或产物校验失败时，构建停止并保留上次成功产物。应修复源码后重新构建，不要通过手改生成文件绕过错误。

搜索站点内容