配置与自定义变量
配置与自定义变量
您可以在 docmd.config.json 中直接定义自定义变量,也可以引用外部 JSON 文件或 JavaScript 模块,并在全站文档中灵活调用。
在 docmd.config.json 中定义
在 docmd.config.json 中添加 variables 配置项:
{
"title": "Acme 云平台文档",
"variables": {
"companyName": "Acme Technologies",
"supportEmail": "support@acme.com",
"cloud": {
"apiEndpoint": "https://api.acme.cloud/v2",
"region": "cn-north-1",
"maxInstances": 50
}
}
}
在 Markdown 中使用
嵌套层级可通过标准点符号访问:
如需技术支持,请发送邮件至 [{{ supportEmail }}](mailto:{{ supportEmail }})。
向生产集群发起请求:
```bash
curl -X GET {{ cloud.apiEndpoint }}/status \
-H "X-Region: {{ cloud.region }}"
```
在执行构建后,将直接编译为:
curl -X GET https://api.acme.cloud/v2/status \
-H "X-Region: cn-north-1"
在客户端 JavaScript 与交互式 Playground 中读取配置变量
所有在 docmd.config.json 中定义的用户变量均会自动序列化并注入客户端运行时(window.__DOCMD_VARIABLES__)。您可以在前端自定义脚本、浏览器扩展以及交互式 Playground 中通过 window.docmd.var.get() 实时检索它们:
// 读取 docmd.config.json 中定义的用户配置变量
const endpoint = window.docmd?.var?.get("cloud.apiEndpoint");
const region = window.docmd?.var?.get("cloud.region");
console.log(`正在连接位于 ${region} 的 API 端点:${endpoint}`);
客户端变量键名与 Markdown 语法完全一致。如果在 Markdown 中书写 {{ cloud.apiEndpoint }},在 JavaScript 中直接通过 window.docmd.var.get("cloud.apiEndpoint") 获取。切勿为用户自定义变量添加 docmd. 前缀。
在配置项字段中直接使用变量
docmd 在渲染整站母版布局、导航和页脚之前,会统一执行变量注册与配置插值阶段。
这意味着您可以在配置文件的任意文本字段中直接引用内置变量(如 {{ docmd.buildYear }})或自定义变量:
{
"title": "Acme Docs",
"variables": {
"companyName": "Acme Cloud Systems"
},
"footer": {
"copyright": "Copyright © {{ docmd.buildYear }} {{ companyName }}。保留所有权利。"
},
"layout": {
"banners": {
"top": {
"content": "**docmd v{{ docmd.version }} 已发布!** — 节点区域:{{ env.DEPLOY_REGION || 'global' }}。"
}
}
}
}
- 统一注册:在
docmd build启动时,VariableRegistry会预先收集所有内置变量、系统环境变量以及用户定义的variables。 - 配置递归插值:docmd 递归遍历
docmd.config.json并替换所有{{ variable }}模板。 - 正文渲染插值:Markdown 解析器基于相同的变量池统一处理页面正文。
- 效果:无论页脚还是正文,所有动态内容保持完全一致,无需任何手动重复。
引用外部变量文件
针对大型项目或跨团队维护,可将 "variables" 指向外部 JSON 或 JavaScript 脚本:
在配置中指定 JSON 相对路径:
{
"variables": "./data/variables.json"
}
./data/variables.json 文件内容示例:
{
"auth": {
"oauthUrl": "https://auth.acme.com/oauth2/token",
"clientId": "acme-portal-production"
},
"limits": {
"rateLimitPerMin": 1200
}
}
指向 JavaScript 脚本以实现动态计算:
{
"variables": "./data/variables.js"
}
./data/variables.js 导出对象或函数:
module.exports = {
dynamicTimestamp: new Date().toLocaleDateString('zh-CN'),
sdkVersion: require('./package.json').version,
activeServices: ['auth', 'billing', 'analytics']
};
通过 JavaScript 模块,可以直接读取 package.json 中的当前发布版本,确保开发文档与代码库版本发布严格同步。