模板 (Templates)

模板 (Template) 是一个 npm 包，它声明 capabilities: ['template']，并提供一组 .ejs partial 覆盖以及自己的 CSS / JS bundle。@docmd/ui 中的解析器会沿着固定的优先级链查找每个 slot 对应的 partial，遇到任何问题都会回退到默认实现。任何模板问题都不会导致构建失败。

快速开始

1. 安装模板

# 0.8.7 随第一个官方模板一起发布 —— 通过 docmd add 流程安装：
npx @docmd/core add summer

2. 在配置中启用

只需设置 一个键 —— theme.name。docmd 会自动判断这个名字指向的是保留的 CSS 主题（default、sky、ruby、retro）还是一个模板包（summer 等）。

{
  "theme": {
    "name": "summer"
  }
}

此后每个页面都会使用 summer 模板的 layout.ejs。您没有覆盖的 slot（侧边栏、页脚等）会自动回退到 @docmd/ui 的默认实现。

{
  "theme": {
    "name": "sky",
    "template": "summer"
  }
}

3. 按页面覆盖

只需一个 frontmatter 键，就能让该页面单独使用其他模板：

---
title: "Changelog"
template: "template-changelog"
---

# Changelog
…

解析链

页面渲染时，解析器自上而下遍历这条链，取首个匹配：

CSS 主题 default、sky、ruby、retro 属于保留名 —— 若 theme.name 命中其中之一，就仍是 CSS 主题。其他任何值都会被视作模板名，对应的 @docmd/template-* 包会自动加载。

若解析到的文件在磁盘上不存在，解析器会打印一条 TUI 警告并回退到默认实现。

支持的模板 slot

模板可以覆盖以下 12 个 slot 中的任何一个。未覆盖的 slot 会回退到默认：

资源优先级

当多个模板与您的 customCss 都提供了 CSS / JS 时，它们按下表顺序加载（数值小的先加载，数值大的在级联冲突中胜出）：

若想覆盖某个模板的样式，请将规则放入项目级 customCss（优先级 15）。请避免在模板 CSS 中使用 !important，这样用户无需 fork 就能调整。

模板本地化

当前 locale 会作为普通 local 传入您的模板。翻译仍通过 t(key) helper 查找 —— 您既有的 assets/i18n/<locale>.json 文件继续有效。

接下来

• 开发模板 —— 编写您自己的模板包。
• 主题定制 —— 在任意模板上叠加 customCss。
• 自定义登录页 —— 把模板首页改成您自己的样子。