站点配置

站点级配置写在 __everkm/everkm.yaml。渲染时合并主题 everkm-theme.yaml 中的 config 与 folders，站点配置覆盖主题默认值。

模板中通过全局变量 __config 读取；目录级规则写在 folders 字段。

最小示例

config:
  timezone: Asia/Shanghai
  default_lang: zh_CN
  site:
    name: 我的站点
    description: 站点简介
    logo: ~/assets/logos/logo.svg

default_template: post.html

folders:
  "/":
    hide_in_url: true
  "/blog/":
    template: list.html
    url_id_suffix: false
  "/docs/":
    template: book.html
    query:
      nav_file: /docs/_nav.md
    breadcrumbs:
      - title: "@i18n:nav.docs"
        url: /docs/

`config` 常用字段

字段	说明
`config.timezone`	时区，默认 `Asia/Chongqing`
`config.default_lang`	默认语言，影响 `@i18n:` 与 `t()` 回退，默认 `en_US`
`config.site`	站点名称、描述、Logo 等，具体字段取决于主题
`config.code_highlight`	对象；`server: true` 时由发布引擎在服务端完成 fenced 代码块着色（主题引入 `code-highlight.css`，输出 `syn-*` class），省略或 `server: false` 时保持浏览器 Prism。嵌入方若无主题 CSS，可走引擎 API `HighlightRenderOptions.inline_theme` 使用内联颜色（见 `highlight-packages/README.md`）
`config.math_render`	对象；`server: true` 时由发布引擎将正文公式渲染为内联 SVG（Typst + mitex，主题可引入 `math-svg.html` 样式片段），省略或 `server: false` 时保持浏览器 KaTeX

config 下的字符串可使用 @i18n:<key> 引用语言包，见多语言。

主题特有配置（如 youlog 的 Algolia 搜索 config.algolia、导航 header_nav）写在 config 下。youlog 各字段说明见 theme-youlog。Algolia 推送与前端搜索配置见嵌入式搜索。

`default_template`

全站默认页面模板名称。某目录未在 folders 中指定 template 时使用。

可被 folders 中同级或子目录的 template 覆盖。

解析优先级（从高到低）：

文章 front matter 的 template
  → 该目录 merged folders.template
  → everkm.yaml#default_template
  → everkm-theme.yaml#default_template

主题可在 everkm-theme.yaml 预设默认值；站点 everkm.yaml 中同名项覆盖主题。

`folders` 目录规则

在 everkm.yaml 中按 URL 路径前缀为目录声明渲染规则；主题可在 everkm-theme.yaml#folders 预设默认值，站点按同 path 键覆盖。子目录与祖先合并继承，深层覆盖浅层。

常用字段：

字段	说明
`url_slug`	自定义 URL 路径段；显式配置后即使无目录 `index.md` 也会进入子孙 URL 前缀
`template`	该目录下页面使用的主题内模板名
`query`	合并进模板全局变量 `__qs` 的键值对
`breadcrumbs`	面包屑；`title` 支持 `@i18n:<key>`
`hide_in_url`	`true` 时该目录段不出现在 URL 中
`url_id_suffix`	默认 `true`；`false` 时 URL 为 `{slug}.html` 而非 `{slug}-{id}.html`
`hash_scatter`	是否将文章哈希分散到子目录导出

完整字段、合并规则与 URL 生成见目录配置。

folders:
  "/blog/":
    template: list
    url_id_suffix: false   # /blog/my-post.html，而非 /blog/my-post-123.html

与主题配置的关系

两个 YAML 各司其职：主题包预设开箱即用的默认值，站点只写差异；并非所有字段都应在两边重复声明。

文件	作用
`__everkm/theme/<name>/everkm-theme.yaml`	主题元信息、主题级默认 `config` / `folders` / `default_template`
`__everkm/everkm.yaml`	站点运营配置，在可合并字段上优先级更高

主题元信息字段见主题开发。

配置归属

字段	`everkm-theme.yaml`	`everkm.yaml`	说明
`name` / `version` / `author` / `repository` / `demo` / `screenshots`	✅	—	主题包元信息，仅主题侧
`config`	✅ 预设	✅ 覆盖	合并后供 `__config` / `config()` 读取
`folders`	✅ 预设	✅ 覆盖	按 path 键 field-level extend，见目录配置
`default_template`	✅ 预设	✅ 覆盖	fallback 链见上文
`inject_js` / `inject_css`	—	✅	站点级 HTML 资源注入，仅项目侧
`redirects`	—	✅	导出 nginx / Vercel 时的额外重定向，仅项目侧

inject_*、redirects 与主题 meta 分属不同配置范围，刻意不在两边都实现：主题自带 JS/CSS 应写在模板或 assets/ 中；重定向与具体部署域名相关，由站点运营者维护；name / version 等描述主题包本身，不属于站点配置。

可合并字段的合并规则

config：主题 config 为底，站点 config 深度合并覆盖（json_patch::merge）。

对象：递归合并，同名 key 站点覆盖主题
数组：整段替换，不是 append（站点写了 config.site.nav 会替换主题同 key 下的整个数组）
渲染前会对 @i18n: 等做 materialize，模板读到的 __config 已是当前语言下的最终值

folders：先合成 effective_folders（主题底、站点按 path extend），再沿文章目录祖先链合并。详见目录配置。

default_template：不参与 merge，按 fallback 链取第一个非空值（站点优先于主题）。

站点专属字段

以下字段仅写在 __everkm/everkm.yaml，主题 everkm-theme.yaml 不支持、也不需要支持。

inject_js / inject_css：在渲染 HTML 的 </head> / </body> 前注入额外资源。每项：

字段	说明
`url`	资源路径；相对路径自动加站点 `base_prefix`
`match_path`	可选 glob；省略或空则匹配所有页面

inject_css:
  - url: ~/assets/extra.css
inject_js:
  - url: https://cdn.example.com/analytics.js
    match_path: "/blog/**"

redirects：导出 --with-nginx-map / --with-vercel 时追加的重定向规则（与索引别名、permalink 生成的 map 合并）。

redirects:
  - source: /old-path
    destination: /new-path
    permanent: true