Doom
  • English

      • MDX

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

      TOC

      rspress Componentsdoom ComponentsOverviewCalloutsCalloutDirectiveExternalSiteExternalSiteLinkAcpApisOverview and ExternalApisOverviewTermpropsTermsTablepropsJsonViewerCustom Component Reuse

      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
      • PackageManagerTabs
      • Steps
      • Tab/Tabs
      • Toc

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

      preview.mdx
      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 importing. Currently, these include:

      Overview

      Document overview component used to display the document directory

      Callouts

      Same as the Callouts Markdown extension feature, source code annotation component

      ```sh
Memory overhead per virtual machine ≈ (1.002 × requested memory) \
              + 218 MiB \  # [!code callout]
              + 8 MiB × (number of vCPUs) \  # [!code callout]
              + 16 MiB × (number of graphics devices) \  # [!code callout]
              + (additional memory overhead) # [!code callout]
```

<Callouts>

1. Required for the processes that run in the `virt-launcher` pod.
2. Number of virtual CPUs requested by the virtual machine.
3. Number of virtual graphics cards requested by the virtual machine.
4. Additional memory overhead:
   - If your environment includes a Single Root I/O Virtualization (SR-IOV) network device or a Graphics Processing Unit (GPU), allocate 1 GiB additional memory overhead for each device.
   - If Secure Encrypted Virtualization (SEV) is enabled, add 256 MiB.
   - If Trusted Platform Module (TPM) is enabled, add 53 MiB.

</Callouts>
      Memory overhead per virtual machine ≈ (1.002 × requested memory) \
              + 218 MiB \  
              + 8 MiB × (number of vCPUs) \  
              + 16 MiB × (number of graphics devices) \  
              + (additional memory overhead)
      1. Required for the processes that run in the virt-launcher pod.
      2. Number of virtual CPUs requested by the virtual machine.
      3. Number of virtual graphics cards requested by the virtual machine.
      4. Additional memory overhead:
        • If your environment includes a Single Root I/O Virtualization (SR-IOV) network device or a Graphics Processing Unit (GPU), allocate 1 GiB additional memory overhead for each device.
        • If Secure Encrypted Virtualization (SEV) is enabled, add 256 MiB.
        • If Trusted Platform Module (TPM) is enabled, add 53 MiB.

      Callout

      Same as the Callout Markdown extension feature, standalone annotation component outside code blocks

      <Callout>1</Callout>
<Callout>A</Callout>

| Header X<Callout>x</Callout> | Header Y<Callout>y</Callout> |
| ---------------------------- | ---------------------------- |
| x                            | y                            |

- <Callout>x</Callout> details of x
- <Callout>y</Callout> details of y
      1 A
      Header XxHeader Yy
      xy
      • x details of x
      • y details of y

      Directive

      Sometimes, due to nested indentation, the custom container syntax may fail; you can use the Directive component instead

      - The directory structure of multilingual documents (`doc/en`) needs to be exactly the same as that under the `doc/zh` directory to ensure that 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 tool 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 that under the doc/zh directory to ensure that 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 tool will automatically generate the target language document directory structure based on doc/zh.

      ExternalSite

      External site reference component

      <ExternalSite name="connectors" />
      Note
      Because DevOps Connectors releases on a different cadence from Alauda Container Platform, the DevOps Connectors documentation is now available as a separate documentation set at DevOps Connectors.

      External site link reference component

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

      In mdx, <ExternalSiteLink name="connectors" href="link" children="Content" /> differs in meaning from the following content

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

      If you do not want the text to be rendered inside a p element, you can pass it via the children prop as shown in the example above.

      AcpApisOverview and ExternalApisOverview

      External site API overview components

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

<ExternalApisOverview name="connectors" />
      Note
      For the introduction to the usage methods of ACP APIs, please refer to ACP APIs Guide.
      Note
      For the introduction to the usage methods of DevOps Connectors APIs, please refer to DevOps Connectors APIs Guide.

      Term

      Terminology component, plain text, dynamically mounted and injected

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

      props

      TermsTable

      Built-in terminology list display component

      <TermsTable />
      NameChineseChinese Bad CasesEnglishEnglish Bad CasesDescription
      company

      灵雀云

      		-

      Alauda

      		-

      公司品牌

      product

      灵雀云容器平台

      		-

      Alauda Container Platform

      		-

      产品品牌

      productShort

      ACP

      		-

      ACP

      		-

      产品品牌简称

      alaudaCloudLink

      Alauda Cloud

      		-

      Alauda Cloud

      		--

      props

      • terms: NormalizedTermItem[], optional, custom terminology list for convenient reuse when rendering custom terms in internal documents

      JsonViewer

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

      Custom Component Reuse

      According to the convention, we can extract reusable content into 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 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 />
      WARNING

      Note: Currently, components exported from .mdx do not support passing props. Refer to this issue. Therefore, for scenarios requiring props passing, please develop using .jsx/.tsx components.