指令速查表

Experimentalv0.4.0-rc

版本关联

当前版本v0.4.0-rc更新日志v0.4.0-rc

这页是 Typematter 的 Markdown 指令速查表。需要看组件的实际渲染效果时，再跳到组件页。

配合组件页一起看

这页适合查写法；如果你想确认组件的渲染效果和留白节奏，再切到组件页。

基本规则

容器指令使用 :::name ... :::，适合包裹多行内容或嵌套其它块。
叶子指令使用 ::name[label]{attrs}，适合单个结构块。
行内指令使用 :name[label]{attrs}，适合段落内的小语义。
布尔属性建议显式写成 required="true"、deprecated="true"，避免内容迁移时歧义。
如果示例里还要再嵌套 Markdown 代码块，外层示例请用 ~~~mdx 包住。

指令一览

指令	类型	用途
`details`	容器	折叠说明 / FAQ
`steps`	容器	步骤流程
`file-tree`	容器	文件树
`cards`	容器	卡片入口
`code-group`	容器	代码或富内容切换
`tab`	容器	`code-group` 子面板
`feature-matrix`	容器	能力矩阵表格
`badge`	行内	行内状态标签
`annotation`	行内	行内注释提示
`endpoint`	容器	API 接口头信息
`param-table`	容器	参数表
`param-field`	叶子	单个参数字段
`response-schema`	容器	返回结构
`schema-field`	叶子 / 容器	返回字段，可嵌套
`do-dont`	容器	最佳实践对比
`do`	容器	正向建议项
`dont`	容器	反向建议项
`version-gate`	容器	版本策略说明
`command-group`	容器	命令切换
`command`	容器	命令面板
`preview-frame`	叶子	图片 / 视频 / iframe 预览
`timeline`	容器	时间线
`release-item`	容器	时间线条目

结构与布局

Details / Steps / File Tree 结构块

mdx

:::details 为什么这样设计把补充说明折叠起来，主线阅读会更干净。::::::steps1. 创建页面。2. 写 frontmatter。3. 运行 `npm run validate:docs`。::::::file-tree- content/  - core-concepts/    - authoring-syntax.mdx- package.json - 项目元信息:::

Cards / FeatureMatrix

mdx

:::cards- [快速开始](/cn/get-started/quickstart) - 安装依赖并初始化文档结构。- [组件体系](/cn/core-concepts/components) - 查看所有组件效果。::::::feature-matrix| 能力 | 免费版 | 专业版 || --- | --- | --- || 静态导出 | 支持 | 支持 || Ask AI | 可选 | 可选 || 双语文档 | 支持 | 支持 |:::

CodeGroup / Tab

mdx

:::code-group```bash [npm]npm installnpm run dev``````bash [pnpm]pnpm installpnpm dev```::::::code-group:::tab[说明]适合放说明文字、截图或迁移提示。::::::tab[配置]```toml[docs]static = true```::::::

行内语义

Badge / Annotation

mdx

Typematter 当前处于 :badge[实验中]{variant="note"} 阶段。这个能力仍有限制：:annotation[先看部署页里的环境变量说明。]{label="i" title="注意"}。

API 文档

Endpoint / ParamTable / ResponseSchema

mdx

:::endpoint{method="GET" path="/v1/docs/[slug]" title="获取文档页面" summary="按路由返回页面元信息。" auth="optional" since="0.4.0-rc"}:::param-table[路径参数]::param-field[slug]{type="string[]" required="true" description="文档路由片段数组。"}::param-field[lang]{type='"cn" | "en"' default="cn" description="语言代码。"}::::::response-schema[200 响应]{code="200" mediaType="application/json"}::schema-field[title]{type="string" required="true" description="页面标题"}:::schema-field[toc]{type="TocItem[]" description="标题目录"}::schema-field[id]{type="string" required="true" description="锚点 id"}::schema-field[level]{type="number" required="true" description="标题层级"}:::::::::

属性速记：

endpoint: method、path 必填；可选 title、summary、auth、since、deprecated、removedIn
param-field: type 必填；可选 required、default、description
response-schema: 可选 code、mediaType
schema-field: type 必填；可选 required、description

规范与迁移

DoDont / VersionGate

mdx

:::do-dont[写 API 文档时]:::do[字段保持稳定]公开字段名和错误码应保持长期稳定。::::::dont[不要把破坏性变更藏进正文]迁移说明应该显式标记。:::::::::version-gate[Legacy search index]{since="0.2.0" deprecated="0.4.0" removedIn="1.0.0" replacement="standard search manifest"}当能力进入迁移期时，把版本策略直接贴在功能块旁边。:::

属性速记：

do-dont: 可选 title，也可用 doTitle / dontTitle 自定义列标题
version-gate: 可选 since、deprecated、removedIn、replacement

命令、预览与时间线

CommandGroup / PreviewFrame / Timeline

mdx

:::command-group[安装 Typematter]:::command[pnpm]{description="推荐"}```bashpnpm installpnpm dev```::::::command[npm]```bashnpm installnpm run dev```::::::::preview-frame[快速开始页面预览]{src="/cn/get-started/quickstart/" caption="同源页面、截图或录屏都可以。"}:::timeline:::release-item[版本关联与中文搜索]{version="0.4.0-rc" date="2026-03-20" status="当前"}增加版本关联面板、文档类型模板、中文别名召回，以及更稳的 Ask AI 检索体验。::::::

属性速记：

command: 标签写在方括号里；可选 platform、description
preview-frame: src 必填；可选 type、caption、ratio、height、allow、poster
release-item: version 必填；可选 date、status

什么时候用 JSX

这套指令语法适合让内容作者保持纯 Markdown 写作体验。遇到下面这几种情况，直接写 MDX JSX 更稳：

需要非常复杂的嵌套结构
需要把 React children 精确放到某个插槽
需要和自定义组件组合，且属性较多

组件级示例与视觉效果仍以组件页为准。