变量与动态运行时概览
变量与动态运行时概览
docmd 拥有高效的变量与个性化运行时引擎,将静态构建期的模板变量插值与客户端浏览器的响应式动态个性化无缝结合。
您无需在数十个 Markdown 文件中硬编码公司名称、API 地址、版本号或版权年份,只需使用简洁优雅的模板语法即可灵活引用动态变量。
欢迎查阅 **{{ site.title }}** v{{ docmd.version }} 官方技术文档!
当前版权所有:© {{ docmd.buildYear }}。
以下数值由 docmd 编译器在本次文档构建过程中实时计算并解析:
- 站点标题: docmd docs
- 编译器版本: v0.10.1
- 构建年份: © 2026
- 当前 Git 分支: main
- 当前 Git 提交: f8f75b6
- 当前页面 Slug:
variables/overview
模板语法
变量引擎使用标准双花括号语法:
{{ variableName }}
默认回退值 (Fallbacks)
当某个变量在当前环境中未定义(例如在本地离线预览或可选配置场景),可通过 || 操作符指定默认回退值:
连接至网关服务器:`{{ server.endpoint || "https://api.example.com" }}`
欢迎回来,{{ user.name || '访客' }}!
针对版本 {{ targetVersion || 2.0 }} 编译。
回退值可支持:
- 单引号字符串:
'示例' - 双引号字符串:
"示例" - 数值:
42或2.0 - 标识符:
default
空白符容错
表达式对变量名与操作符前后的空格完全宽容:
{{ myVar }}
{{ env.PORT || "8080" }}
Markdown 语法与 JavaScript API 映射对照
所有在 Markdown 模板中可用的变量均与客户端 JavaScript SDK (window.docmd.var.get()) 保持 1:1 严格映射:
| 变量类别 | Markdown 模板占位符 | 客户端 JavaScript API | 命名空间规范 |
|---|---|---|---|
| 用户 / 项目自定义变量 | {{ apiEndpoint }} |
window.docmd.var.get("apiEndpoint") |
在 docmd.config.json 或前言中定义。绝无 docmd. 前缀。 |
| 嵌套自定义变量 | {{ cloud.apiEndpoint }} |
window.docmd.var.get("cloud.apiEndpoint") |
配置中的嵌套 JSON 对象。使用点号访问。 |
| 编译器引擎版本 | {{ docmd.version }} |
window.docmd.var.get("docmd.version") |
专用 docmd. 命名空间,代表编译器内置元数据。 |
| 构建发布年份 | {{ docmd.buildYear }} |
window.docmd.var.get("docmd.buildYear") |
专用 docmd. 命名空间。 |
| Git 仓库元数据 | {{ docmd.gitCommit }} |
window.docmd.var.get("docmd.gitCommit") |
专用 docmd. 或 git. 命名空间。 |
| 站点全局元数据 | {{ site.title }} |
window.docmd.var.get("site.title") |
专用 site. 命名空间,取自配置文件。 |
| 动态用户会话变量 | {{ user.apiKey }} |
window.docmd.var.get("user.apiKey") |
以 user. 开头或在 dynamic 中声明。DOM 实时响应。 |
{{ docmd.apiEndpoint }}?docmd.命名空间(如docmd.version、docmd.buildYear、docmd.gitCommit等)严格为 docmd 内部编译器引擎元数据保留。- 任何由用户自定义的变量(来自
docmd.config.json或 Markdown 前言)切勿添加docmd.前缀。如果您配置了"apiEndpoint": "https://api.example.com",请在 Markdown 中书写{{ apiEndpoint }},在 JavaScript 中通过window.docmd.var.get("apiEndpoint")读取。
变量生命周期:构建期 vs 运行时
docmd 将变量生命周期清晰解耦为两个高效阶段:
在执行 docmd build 时直接内嵌编译至 HTML。在浏览器中零 JS 运行耗时、零网络请求、零累积布局偏移 (CLS)。
用户会话与交互变量(如 API Key 和用户名)由 docmd-runtime.js 实时水合。一旦修改,页面所有代码块即刻动态响应。
构建期静态变量
构建期确定的系统元数据和全局配置会被直接烘焙进最终的 HTML 代码中,对最终读者没有任何渲染延迟。
客户端动态变量
被标记为 dynamic 或以 user. 开头的变量,会在 HTML 中被轻量级的响应式标记所包裹:
访客
在浏览器加载后,docmd-runtime.js 会自动根据当前用户的登录信息或输入框内容刷新对应的值,并在 SPA 无刷新页面切换时保持同步。
架构:引擎与界面的严格分离
为了保障极致的性能与系统的长久稳定性,docmd 严格区分了前端呈现与动态运行时内核:
docmd-runtime.js:通用无头(Headless)动态引擎,内置于包括默认模板和summer在内的所有主题中。专注于变量管理、状态持久化与跨窗口事件,绝不干涉 DOM 样式与视觉动画。docmd-main.js:UI 呈现层脚本,负责主题切换、移动端抽屉导航与 SPA 路由。每次页面跳转完成后会自动调用window.docmd.sync()确保新内容完全水合。
无论使用官方模板还是第三方主题扩展,docmd-runtime.js 均会自动加载,开箱即用支持完整的个性化动态变量。
深入探索
浏览以下详细指南以掌握各类变量的配置与用法: