Doom
  • 简体中文

      • MDX

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

      目录

      rspress 组件doom 组件OverviewCalloutsCalloutDirectiveExternalSiteExternalSiteLinkAcpApisOverview 与 ExternalApisOverviewTermpropsTermsTablepropsJsonViewer自定义组件复用

      rspress 组件

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

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

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

      preview.mdx
      import { SourceCode } from '@rspress/core/theme'

<SourceCode href="/" />

      doom 组件

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

      Overview

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

      Callouts

      同 Callouts Markdown 扩展功能，源码标注组件

      ```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

      同 Callout Markdown 扩展功能，代码块外独立标注组件

      <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

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

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

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

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

        注意

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

      ExternalSite

      引用外部站点组件

      <ExternalSite name="connectors" />
      Note
      因为 DevOps 连接器的发版周期与灵雀云容器平台不同，所以 DevOps 连接器的文档现在作为独立的文档站点托管在 DevOps 连接器。

      引用外部站点链接组件

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

      在 mdx 中 <ExternalSiteLink name="connectors" href="link" children="Content" /> 与下面的内容含义不同

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

      如果不希望文本渲染在 p 元素内，可以像上面的示例一样使用 children 属性传递

      AcpApisOverview 与 ExternalApisOverview

      引用外部站点 API 概览组件

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

<ExternalApisOverview name="connectors" />
      Note
      关于 ACP APIs 的使用方法介绍请参考 ACP APIs 指南。
      Note
      关于 DevOps 连接器 APIs 的使用方法介绍请参考 DevOps 连接器 APIs 指南。

      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 />
      名称中文中文反例英文英文反例描述
      company

      灵雀云

      		-

      Alauda

      		-

      公司品牌

      product

      灵雀云容器平台

      		-

      Alauda Container Platform

      		-

      产品品牌

      productShort

      ACP

      		-

      ACP

      		-

      产品品牌简称

      alaudaCloudLink

      Alauda Cloud

      		-

      Alauda Cloud

      		--

      props

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

      JsonViewer

      <JsonViewer value={{ key: 'value' }} />
      yaml
      json
      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 />
      WARNING

      注意：目前 .mdx 导出的组件不支持 props 传参，参考此 issue，因此需要传递 props 的场景请使用 .jsx/.tsx 组件进行开发