技能介绍

解决静态文档的动态渲染瓶颈

在编写技术文档或产品手册时，纯静态的 Markdown 往往难以满足复杂的交互需求。当文档需要展示动态数据、特定业务逻辑的计算结果，或者复用全局的配置参数时，传统 Markdown 只能依赖外部脚本或繁琐的预处理。这导致文档维护成本高，且内容结构难以标准化。

核心能力与工作流

Markdoc 通过引入自定义扩展来突破这一限制。其核心机制包括：

自定义标签（Custom Tags）：允许在 Markdown 中嵌入特定 UI 组件或结构化数据块，实现内容的模块化复用。
函数（Functions）：支持在文档中直接调用外部函数进行实时计算或数据获取。
变量（Variables）：通过变量引用全局配置或动态值，确保文档内容的一致性。

在工作流中，开发者首先使用 Markdoc 解析器处理 .md 文件，生成包含标签、函数和变量的抽象语法树（AST）。随后，这些节点可以被渲染为 React 组件或其他前端框架的元素，从而实现文档与代码逻辑的深度绑定。

适用边界与注意事项

虽然 Markdoc 提供了强大的扩展能力，但它主要聚焦于文档站点的构建，并非通用的前端状态管理方案。在使用自定义标签和函数时，需要确保服务端或构建环境的依赖正确配置。例如，在 TypeScript 环境中，必须设置 moduleResolution 为 node 以避免模块解析错误。此外，过度依赖动态函数可能会影响文档的静态生成（SSG）性能，建议根据实际渲染需求权衡使用。