变量与动态运行时概览

变量与动态运行时概览

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 将变量生命周期清晰解耦为两个高效阶段:

变量解析流水线架构图
graph TD subgraph 来源["1. 输入与定义来源"] B1["docmd.config.json<br/><code>variables</code> 配置块"] B2["Git 与系统环境变量<br/><code>env.*</code>, <code>DOCMD_VAR_*</code>, Git 仓库"] B3["内置动态元数据<br/><code>version</code>, <code>buildYear</code>, <code>page.slug</code>"] end subgraph 编译期["2. 构建期静态解析 (@docmd/parser)"] 来源 --> VReg["VariableRegistry 注册表"] VReg --> Interp["Markdown 与配置项插值器"] Interp --> HTML["纯静态 HTML (零 JS 开销)"] Interp --> Markers["动态标记 &lt;span data-docmd-var&gt;"] end subgraph 运行时["3. 客户端响应式运行时"] Markers --> DRuntime["docmd-runtime.js (window.docmd)"] DRuntime --> DOM["页面实时渲染与代码块同步"] DRuntime --> Events["跨窗口 postMessage 与事件总线"] end
构建期静态变量

在执行 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 均会自动加载,开箱即用支持完整的个性化动态变量。

深入探索

浏览以下详细指南以掌握各类变量的配置与用法:

内置变量参考

版本号、构建时间、年份及 Git 提交元数据。
阅读指南

配置与自定义变量

在 docmd.config.json 中定义并在页脚、公告栏与文档中引用。
阅读指南

系统环境变量

CI/CD 流水线集成与 DOCMD_VAR_* 免前缀自动提升。
阅读指南

客户端运行时与个性化

浏览器 SDK (window.docmd)、动态用户凭证与交互式代码块。
阅读指南