#MDX

MDX 是一种 Markdown 的扩展语法，允许在 Markdown 中使用 JSX 语法，使用方式可以参考 rspress MDX。

#rspress 组件

rspress 主题提供的内置组件大部分已调整为全局组件，可以在 .mdx 文件中无需导入直接使用，包括：

• Badge
• Card
• LinkCard
• PackageManagerTabs
• Steps
• Tab/Tabs
• Toc

其他不常用的组件可以通过 rspress/theme 导入使用，例如：

import { SourceCode } from '@rspress/core/theme'

<SourceCode href="/" />

#doom 组件

doom 提供了一些全局组件来辅助文档编写，不需要导入即可直接使用，目前包括：

#Overview

文档概览组件，用于展示文档目录

#Directive

有时，由于嵌套缩进，自定义容器语法可能失效，可以使用 Directive 组件代替

- 多语言文档(`doc/en`)的目录结构需要与 `doc/zh` 目录下的文档完全一致，保证多语言文档的链接除了语言标识外完全相同。

  <Directive type="danger" title="注意">
    如果是使用自动化翻译工具进行翻译，则无需关心该问题，自动化翻译工具会自动根据
    `doc/zh` 生成目标语言文档的目录结构。
  </Directive>

• 多语言文档(doc/en)的目录结构需要与 doc/zh 目录下的文档完全一致，保证多语言文档的链接除了语言标识外完全相同。

  注意

  如果是使用自动化翻译工具进行翻译，则无需关心该问题，自动化翻译工具会自动根据 doc/zh 生成目标语言文档的目录结构。

#ExternalSite

引用外部站点组件

<ExternalSite name="connectors" />

#ExternalSiteLink

引用外部站点链接组件

<ExternalSiteLink name="connectors" href="link.mdx#hash" children="Content" />

<ExternalSiteLink name="connectors" href="link">
  Content {/* 将渲染在 `p` 元素内 */}
</ExternalSiteLink>

#AcpApisOverview 与 ExternalApisOverview

引用外部站点 API 概览组件

<AcpApisOverview />
{/* same as following */}
<ExternalApisOverview name="acp" />

<ExternalApisOverview name="connectors" />

#Term

术语组件，纯文本，动态挂载注入

<Term name="company" textCase="capitalize" />
<Term name="product" textCase="lower" />
<Term name="productShort" textCase="upper" />
<Term name="alaudaCloudLink" />

#props

• name: 内置术语名称，参考动态挂载配置文件
• textCase: 文本大小写转换，可选值为lower, upper, capitalize

#TermsTable

内置术语列表展示组件

<TermsTable />

#props

• terms: NormalizedTermItem[]，可选，自定义术语列表，方便内部文档渲染自定义术语时复用

#JsonViewer

<JsonViewer value={{ key: 'value' }} />

key: value

{
  "key": "value"
}

#自定义组件复用

根据约定，我们可以将需要复用的内容抽取到 shared 目录中，然后在需要的地方引入即可，比如：

import CommonContent from './shared/CommonContent.mdx'

<CommonContent />

如果需要使用更多 runtime 相关的 API，可以使用 .jsx/.tsx 实现组件，然后在 .mdx 文件中引入使用。

// shared/CommonContent.tsx
export const CommonContent = () => {
  const { page } = usePageData()
  return <div>{page.title}</div>
}

// showcase/content.mdx
import { CommonContent } from './shared/CommonContent'
;<CommonContent />