MDX 组件

Doctrine 会在每个 MDX 页面注册内置组件，因此在 MDX 中无需 import。自定义模块也可以从 @amamo/doctrine/components 导入组件值与 prop 类型。

内置组件

下面会在每个公开组件的示例旁介绍对应 props。“其他属性”表示组件也接受表格中列出的 React 原生属性，包括 className、id、aria-* 和 data-*。

原生写作元素

Doctrine 会直接排版语义化 HTML，因此常见写作模式不需要额外的 React 组件。Markdown 引用与表格照常使用；MDX 还可以用 <details> 和 <summary> 展开补充内容，用 <kbd> 表示键盘输入，用 <mark> 标出重点，用 <dl> 编写定义列表，并用 <figure> 和 <figcaption> 为媒体添加说明。这些元素会沿用主题、窄屏布局、焦点样式和打印样式。

MDX

<details>  <summary>为什么产物是静态的？</summary>构建时会预渲染每条路由。</details>按 <kbd>Ctrl</kbd> + <kbd>K</kbd> 搜索。

为什么产物是静态的？

构建时会预渲染每条路由。

按 Ctrl + K 搜索。

标题与本页目录

@amamo/mdx 在编译页面时生成标题 ID 和目录数据，Doctrine 会把这份数据直接渲染进初始 HTML，并保留标题中的行内格式。重复标题会依次添加 -1、-2 等后缀。需要指定稳定锚点时，在标题末尾添加 [#custom-id]，该标记不会出现在页面中：

MDX

## 运行时生命周期 [#runtime]

代码块

Fenced code block 在浅色和深色模式下分别使用 One Light 与 Andromeeda，默认显示检测到的语言及可用图标，并提供复制操作。需要显示文件名时，在 fence metadata 中添加 filename="..."：

MDX

```ts filename="doctrine.config.ts"export default {  title: 'Documentation',}```

TypeScriptdoctrine.config.ts

export default {  title: 'Documentation',}

代码 metadata 与行内注解会在编译阶段处理。用 {2,4-5} 高亮行，用 /createApp/ 高亮匹配单词，或在行尾写 // [!code ...] 并使用 highlight、focus、++、--、error、 warning、info、word:value。渲染和复制代码时不会保留注解注释。

MDX

```ts filename="app.ts" {1} /createApp/const app = createApp()app.mount('#root')app.start() // [!code ++]```

TypeScriptapp.ts

const app = createApp()app.mount('#root')app.start()

Callout

用 Callout 将补充说明、建议、警告和阻塞问题与正文区分开。

Prop	类型	必填	默认值	说明
`children`	`ReactNode`	否	—	Callout 正文
`title`	`string`	否	—	显示在正文上方的标题
`variant`	`"note" \| "tip" \| "warning" \| "danger"`	否	`"note"`	配色与图标样式
其他属性	`HTMLAttributes<HTMLElement>`	否	—	传给根 `<aside>` 元素

MDX

<Callout variant="tip" title="可以部署">  上传 `dist` 前先运行生产构建。</Callout>

Badge

用 Badge 在句子或标题中展示简短状态和标签。

Prop	类型	必填	默认值	说明
`children`	`ReactNode`	否	—	Badge 内容
`variant`	`"default" \| "outline"`	否	`"default"`	实心或描边样式
其他属性	`HTMLAttributes<HTMLSpanElement>`	否	—	传给根 `<span>` 元素

MDX

<Badge>稳定</Badge> <Badge variant="outline">预览</Badge>

稳定预览

Card 与 CardGrid

Card

Card 是展示容器而不是链接。需要跳转时，请在 Card 内放 Markdown 链接。

Prop	类型	必填	默认值	说明
`children`	`ReactNode`	否	—	Card 正文
`title`	`string`	否	—	显示在正文上方的标题
其他属性	`HTMLAttributes<HTMLDivElement>`	否	—	传给根 `<div>` 元素

MDX

<Card title="安装">从[入门教程](/zh-CN/getting-started/)开始。</Card>

安装

从入门教程开始。

CardGrid

用 CardGrid 在窄屏下单列、空间足够时双列排列 Card。

Prop	类型	必填	默认值	说明
`children`	`ReactNode`	否	—	Card 或其他网格项目
其他属性	`HTMLAttributes<HTMLDivElement>`	否	—	传给根 `<div>` 元素

MDX

<CardGrid>  <Card title="安装">从[入门教程](/zh-CN/getting-started/)开始。</Card>  <Card title="部署">复制 [GitHub Pages 工作流](/zh-CN/deployment/)。</Card></CardGrid>

安装

从入门教程开始。

部署

复制 GitHub Pages 工作流。

Steps 与 Step

Steps

Steps 渲染有序流程，并为每个直接子级 Step 编号。

Prop	类型	必填	默认值	说明
`children`	`ReactNode`	否	—	一组 `Step` 元素
其他属性	`HTMLAttributes<HTMLOListElement>`	否	—	传给根 `<ol>` 元素

MDX

<Steps>  <Step title="编写">创建 MDX 文件。</Step>  <Step title="预览">启动开发服务器。</Step>  <Step title="构建">生成静态文件。</Step></Steps>

编写
创建 MDX 文件。
预览
启动开发服务器。
构建
生成静态文件。

Step

Step 只能放在 Steps 中；可见编号由父级列表提供。

Prop	类型	必填	默认值	说明
`children`	`ReactNode`	否	—	步骤正文
`title`	`string`	否	—	显示在步骤正文上方
其他属性	`HTMLAttributes<HTMLLIElement>`	否	—	传给根 `<li>` 元素

LivePreview

LivePreview 渲染普通 MDX children，因此 React 事件会随页面一起 hydration。传入 source 可以增加原生的源码折叠区；Doctrine 不会额外引入浏览器编译器或编辑器。

Prop	类型	必填	默认值	说明
`children`	`ReactNode`	是	—	渲染的预览内容
`language`	`string`	否	`"tsx"`	可选源码块的语言标签
`source`	`string`	否	—	折叠区中显示的源码
`title`	`ReactNode`	否	—	显示在预览上方的标题
其他属性	`Omit<HTMLAttributes<HTMLElement>, "title">`	否	—	传给根 `<section>` 元素

MDX

<LivePreview source={`<PreviewCounter />`} title="交互式计数器">  <PreviewCounter /></LivePreview>

交互式计数器

源码tsx

TSX

<PreviewCounter />

FileTree

FileTree 为静态语义文件列表提供根容器。

Prop	类型	必填	默认值	说明
`children`	`ReactNode`	是	—	Folder 和 file 条目
其他属性	`HTMLAttributes<HTMLDivElement>`	否	—	传给根 `<div>` 元素

MDX

<FileTree>  <FileTreeFolder name="docs">    <FileTreeFile active name="index.mdx" />    <FileTreeFile name="getting-started.mdx" />  </FileTreeFolder>  <FileTreeFile name="doctrine.config.ts" />  <FileTreeFile name="package.json" /></FileTree>

docs
- index.mdx
- getting-started.mdx
doctrine.config.ts
package.json

FileTreeFolder

在 FileTree 中使用 FileTreeFolder 对嵌套文件夹和文件分组。

Prop	类型	必填	默认值	说明
`children`	`ReactNode`	是	—	嵌套的文件夹与文件条目
`name`	`ReactNode`	是	—	显示的文件夹名称
其他属性	`HTMLAttributes<HTMLLIElement>`	否	—	传给根 `<li>` 元素

FileTreeFile

在 FileTree 或 FileTreeFolder 中使用 FileTreeFile。只给当前示例所表示的文件设置 active。

Prop	类型	必填	默认值	说明
`active`	`boolean`	否	`false`	标记当前文件
`name`	`ReactNode`	是	—	显示的文件名称
其他属性	`HTMLAttributes<HTMLLIElement>`	否	—	传给根 `<li>` 元素

InstallTabs

InstallTabs 为一个包生成 pnpm、npm、Yarn 和 Bun 安装命令。

Prop	类型	必填	默认值	说明
`dev`	`boolean`	否	`false`	添加各包管理器的开发依赖参数
`packageName`	`string`	是	—	每条命令使用的包名

MDX

<InstallTabs packageName="@amamo/doctrine" />

Shell

pnpm add @amamo/doctrine

Shell

npm install @amamo/doctrine

Shell

yarn add @amamo/doctrine

Shell

bun add @amamo/doctrine

Tabs 与 Tab

Tabs

用 Tabs 组合相关面板。未提供 defaultValue 时会选择第一个 Tab。

Prop	类型	必填	默认值	说明
`children`	`ReactNode`	是	—	一组 `Tab` 元素
`className`	`string`	否	—	根元素的 class
`defaultValue`	`string`	否	第一个 Tab 值	初始选中的 Tab
`variant`	`"default" \| "line"`	否	`"default"`	Tab 列表样式

MDX

<Tabs defaultValue="preview" variant="line">  <Tab label="预览" value="preview">    渲染结果  </Tab>  <Tab label="源码" value="source">    MDX 源码  </Tab></Tabs>

渲染结果

Tab

Tab 只能放在 Tabs 中；它声明一个 Tab 控件及其对应面板。

Prop	类型	必填	默认值	说明
`children`	`ReactNode`	是	—	面板内容
`label`	`ReactNode`	是	—	Tab 控件内容
`value`	`string`	否	从 0 开始的索引	稳定的 Tab 与面板键

需要添加项目专属名称或覆盖内置组件时，请继续阅读自定义。