MDX 组件
MDX 组件
docmd 通过 @docmd/plugin-mdx 插件提供对 MDX 及 JSX 组件的内置支持。在 lite-mdx 的驱动下,JSX 标签在构建期被直接编译为无障碍 HTML 及原生 docmd 容器,客户端完全零 JavaScript 运行时开销。
.md 与 .mdx 文件扩展名均可自由使用。
为什么在 docmd 中使用 MDX?
MDX 为从 Nextra、Docusaurus 或 Mintlify 等框架迁移而来的团队提供了熟悉的编写体验,无需重写现有 Markdown 内容即可平滑渲染组件。
安装与配置
安装官方 MDX 插件:
docmd add mdx
或者在你的 docmd.config.json 中声明该插件:
{
"plugins": {
"mdx": {}
}
}
内置组件映射
该插件将常见文档组件直接映射为原生 docmd 容器:
提示框 (<Callout>)
<Callout type="tip" title="专业提示">
在同一篇文档中可自由使用标准 JSX 标签或 docmd 原生容器。
</Callout>
<Callout type="warning" title="注意事项">
请在构建前确保依赖包已完成更新。
</Callout>
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
type |
String |
info |
提示框样式类型(info、tip、warning、danger)。 |
title |
String |
undefined |
顶部展示的标题文本。 |
icon |
String |
undefined |
可选的 Lucide 图标名称或 Iconify 标识。 |
卡片与网格布局 (<Card>, <Cards>)
将链接与导览项组合为响应式网格布局:
<Cards cols={2}>
<Card title="快速上手" href="/getting-started/quick-start" icon="rocket">
了解如何初始化并配置你的第一个 docmd 文档站点。
</Card>
<Card title="CLI 参考" href="/reference/cli-commands" icon="terminal">
完整的命令行接口命令、参数选项与诊断工具。
</Card>
</Cards>
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
cols |
Number |
2 |
网格列数(1、2、3 或 4)。 |
title |
String |
undefined |
卡片标题。 |
href |
String |
undefined |
链接目标地址。 |
icon |
String |
undefined |
卡片图标标识。 |
选项卡 (<Tabs>, <Tab>)
呈现跨平台代码片段或多语言指南:
<Tabs>
<Tab label="pnpm">
```bash
pnpm add docmd
```
</Tab>
<Tab label="npm">
```bash
npm install docmd
```
</Tab>
<Tab label="bun">
```bash
bun add docmd
```
</Tab>
</Tabs>
同样支持复合点号标签写法:
<Tabs>
<Tabs.Tab label="macOS">
`brew install docmd`
</Tabs.Tab>
<Tabs.Tab label="Linux">
`curl -fsSL https://docmd.io/install.sh | sh`
</Tabs.Tab>
</Tabs>
步骤条 (<Steps>)
创建带序号的分步安装向导与实战教程:
<Steps>
### 初始化项目
在项目根目录下执行 `docmd init`。
### 添加文档
使用 Markdown 或 MDX 在 `docs/` 目录下编写文档页面。
### 构建站点
执行 `docmd build` 生成可用于生产发布的静态网页。
</Steps>
语法对比
你可以根据个人习惯或现有项目规范自由选择原生容器语法或 JSX 标签:
| 特性 | 原生容器 (:::) |
MDX 组件 (<Component>) |
|---|---|---|
| 语法风格 | Markdown 原生风格 (::: callout) |
JSX/React 风格 (<Callout>) |
| 依赖环境 | 完全零外部依赖 | 通过 @docmd/plugin-mdx 内置集成 |
| 复合层级 | 嵌套容器结构 | 点号标记法 (<Tabs.Tab>) |
| 表达式 | 模板变量 ($var) |
动态计算表达式 ({expr}) |
| 迁移通用性 | 最清爽的纯文本 Markdown | 直接兼容 Docusaurus / Nextra |
完整语法参考
有关表达式、属性类型及注释语法的完整规范,请参阅 MDX 语法指南。