#MDX

MDX is an extension syntax of Markdown that allows the use of JSX syntax within Markdown. For usage, refer to rspress MDX.

#rspress Components

Most of the built-in components provided by the rspress theme have been adjusted to global components, which can be used directly in .mdx files without importing, including:

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

Other less commonly used components can be imported from rspress/theme, for example:

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

<SourceCode href="/" />

#doom Components

doom provides some global components to assist in documentation writing, which can be used directly without import. Currently, these include:

#Overview

Document overview component, used to display the document directory

#Directive

Sometimes, due to nested indentation, the custom container syntax may fail. You can use the Directive component as a substitute.

- The directory structure of multilingual documents (`doc/en`) needs to be exactly the same as the documents under the `doc/zh` directory to ensure that the links in multilingual documents are identical except for the language identifier.

  <Directive type="danger" title="Note">
    If you are using automated translation tools, you do not need to worry about
    this issue, as the automated translation tools will automatically generate
    the target language document directory structure based on `doc/zh`.
  </Directive>

• The directory structure of multilingual documents (doc/en) needs to be exactly the same as the documents under the doc/zh directory to ensure that the links in multilingual documents are identical except for the language identifier.

  Note

  If you are using automated translation tools, you do not need to worry about this issue, as the automated translation tools will automatically generate the target language document directory structure based on doc/zh.

#ExternalSite

Component for referencing external sites

<ExternalSite name="connectors" />

#ExternalSiteLink

Component for referencing external site links

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

<ExternalSiteLink name="connectors" href="link">
  Content {/* This will be rendered inside a `p` element */}
</ExternalSiteLink>

#AcpApisOverview and ExternalApisOverview

Components for referencing external site API overviews

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

<ExternalApisOverview name="connectors" />

#Term

Term component, plain text, dynamically mounted and injected

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

#props

• name: Built-in term name, refer to dynamic mounting configuration file
• textCase: Text case transformation, optional values are lower, upper, capitalize

#TermsTable

Built-in term list display component

<TermsTable />

#props

• terms: NormalizedTermItem[], optional, custom term list to facilitate reuse when rendering custom terms in internal documentation

#JsonViewer

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

#Custom Component Reuse

According to the convention, we can extract reusable content into the shared directory and then import it where needed, for example:

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

<CommonContent />

If you need to use more runtime related APIs, you can implement components in .jsx/.tsx and then import and use them in .mdx files.

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

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