MDX 组件

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

内置组件

组件	主要 props
`Badge`	`variant="default" \| "outline"` 和 span 属性
`Callout`	`variant="note" \| "tip" \| "warning" \| "danger"`、`title`、aside 属性
`Card`、`CardGrid`	可选 card `title` 和普通 div 属性
`CodeBlock`	可选 `filename`/`language`；包裹 fenced code block
`FileTree` 系列	folder/file 的 `name`；file 可选 `active` 状态
`InstallTabs`	`packageName` 和可选 `dev`；展示 pnpm、npm、yarn、bun 命令
`LivePreview`	渲染的 children；可选 `title`、`source` 和 `language`
`Step`、`Steps`	可选 step `title` 和列表属性
`Tab`、`Tabs`	tab `label`/`value`；tabs `defaultValue`/`className`

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

原生写作元素

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 搜索。

代码块

Fenced code block 在浅色和深色模式下分别使用 One Light 与 Andromeeda，默认显示检测到的语言并提供复制操作。需要同时显示文件名时，用 CodeBlock 包裹代码围栏：

MDX

<CodeBlock filename="doctrine.config.ts">

```ts
export default {
  title: 'Documentation',
}
```

</CodeBlock>

doctrine.config.tsTypeScript

export default {
  title: 'Documentation',
}

Callout 与 Badge

MDX

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

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

稳定预览

Card 与 Steps

MDX

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

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

安装

从入门教程开始。

部署

复制 GitHub Pages 工作流。

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

实时预览

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

MDX

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

交互式计数器

源码

TSX

<PreviewCounter />

文件树

用 folder 和 file 组合静态语义列表。只给当前示例所表示的文件添加 active。

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

安装命令与 Tabs

InstallTabs 使用内置 Tabs 和代码块组合出各包管理器对应的安装命令。其他选项卡内容仍可直接使用 Tabs 与 Tab。

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

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