模板 (Templates)

模板 (Templates)

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

快速开始

1. 安装模板

# 安装官方模板包：
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 会回退到默认：

层叠顺序

当模板与样式表结合使用时，样式按可预测的三阶段顺序加载：

1. 核心与主题：基础样式和主题配色优先加载。
2. 模板与插件：结构布局规则和插件资源随后加载。
3. 自定义 CSS 与 JS：您的 customCss 和 customJs 文件最后加载，始终优先于模板生效。

若想覆盖某个模板的样式，请将规则放入项目级 theme.customCss。

模板本地化

当前 locale 会作为普通变量传入您的模板。翻译仍通过 t(key) 辅助函数查找，您既有的 assets/i18n/<locale>.json 文件继续有效。

相关资源

• 开发模板：编写您自己的模板包。
• 主题定制：在任意模板上叠加 customCss。
• 自定义落地页：将模板首页定制为您自己的外观。