#MDX

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

#rspress Components

The rspress theme provides a majority of the built-in components as global components, which can be used directly in .mdx files without import, including:

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

Other less frequently used components can be imported from @rspress/core/theme, for example:

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

<SourceCode href="/" />

#doom Components

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

#Overview

Component for document overview, used to display the document directory.

#Directive

Sometimes, due to nested indentation, the custom container syntax may become invalid. The Directive component can be used as a substitute.

- The directory structure of multi-language documents (`doc/en`) needs to be fully consistent with the documents under the `doc/zh` directory to ensure that the links of multi-language documents are identical except for the language identifier.

  <Directive type="danger" title="Attention">
    If automated translation tools are used for translation, there is no need to
    worry about this issue, as the automated translation tools will
    automatically generate the directory structure of the target language
    documents based on `doc/zh`.
  </Directive>

• The directory structure of multi-language documents (doc/en) needs to be fully consistent with the documents under the doc/zh directory to ensure that the links of multi-language documents are identical except for the language identifier.

  Attention

  If automated translation tools are used for translation, there is no need to worry about this issue, as the automated translation tools will automatically generate the directory structure of the target language documents based on doc/zh.

#ExternalSite

Component to reference external sites.

<ExternalSite name="connectors" />

#ExternalSiteLink

Component to reference 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 andExternalApisOverview

Components to reference external site API overviews.

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

<ExternalApisOverview name="connectors" />

#Term

Term component for plain text, dynamically mounted for injection.

<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

Component for displaying a list of built-in terms.

<TermsTable />

#props

• terms: NormalizedTermItem[], optional, a custom term list for reusing when rendering custom terms in internal documentation.

#JsonViewer

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

key: value

#Custom Component Reuse

According to conventions, we can extract reusable content to the shared directory, 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 using .jsx/.tsx and then import them into .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 />