Docusaurus 的 MDX 基本语法

2023年8月29日 👁️‍🗨️阅读需 13 分钟

cq329

瞎折腾的奶爸

Docusaurus 2 使用 MDX 作为解析引擎，它不仅仅可以解析标准 Markdown 语法，还可以在文档中渲染 React 组件。下面让我带您体验 MDX 的全新特性吧！

mdx

1. 选项卡

Docusaurus <Tabs> 借助 MDX 提供了可以在 Markdown 中使用的组件：

语法示例 1：

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="apple" label="Apple" default>
    This is an apple 🍎
  </TabItem>
  <TabItem value="orange" label="Orange">
    This is an orange 🍊
  </TabItem>
  <TabItem value="banana" label="Banana">
    This is a banana 🍌
  </TabItem>
</Tabs>

效果：

Apple
Orange
Banana

This is an apple 🍎

语法示例 2：

<Tabs
  defaultValue="apple"
  values={[
    {label: 'Apple', value: 'apple'},
    {label: 'Orange', value: 'orange'},
    {label: 'Banana', value: 'banana'},
  ]}>
  <TabItem value="apple">This is an apple 🍎</TabItem>
  <TabItem value="orange">This is an orange 🍊</TabItem>
  <TabItem value="banana">This is a banana 🍌</TabItem>
</Tabs>

效果：

Apple
Orange
Banana

This is an apple 🍎

设置默认选项卡

default 默认情况下显示第一个选项卡，您可以通过添加到其中一个选项卡项目来指定默认选项卡。您还可以将组件 defaultValue 的 prop 设置 Tabs 为您选择的标签值。例如，在上面的示例中，选项卡 default 的设置 value="apple" 或 defaultValue="apple" 选项卡的设置强制默认打开 “Apple” 选项卡。如果您希望默认情况下不显示任何选项卡，请使用 defaultValue={null}。

语法示例 1：

默认显示 Oranage 选项卡

<Tabs>
  <TabItem value="apple" label="Apple">
    This is an apple 🍎
  </TabItem>
  <TabItem value="orange" label="Orange" default>
    This is an orange 🍊
  </TabItem>
  <TabItem value="banana" label="Banana">
    This is a banana 🍌
  </TabItem>
</Tabs>

效果：

Apple
Orange
Banana

This is an orange 🍊

语法示例 2：

默认显示 Banana 选项卡

<Tabs
  defaultValue="banana"
  values={[
    {label: 'Apple', value: 'apple'},
    {label: 'Orange', value: 'orange'},
    {label: 'Banana', value: 'banana'},
  ]}>
  <TabItem value="apple">This is an apple 🍎</TabItem>
  <TabItem value="orange">This is an orange 🍊</TabItem>
  <TabItem value="banana">This is a banana 🍌</TabItem>
</Tabs>

效果：

Apple
Orange
Banana

This is a banana 🍌

同步选项卡

您可能希望同类选项卡的选择能够彼此同步。例如，您可能希望为 Windows 上的用户与 macOS 上的用户提供不同的说明，并且您希望一键更改所有特定于操作系统的说明选项卡。为此，您可以为所有相关选项卡提供相同的 groupId 属性。请注意，这样做将保留该选择，localStorage 并且当其中一个实例的值发生更改时，<Tab> 具有相同选项的所有实例都会自动更新。groupId 请注意，组 ID 是全局命名空间的。

语法示例 1：

<Tabs groupId="operating-systems">
  <TabItem value="win" label="Windows">Use Ctrl + C to copy.</TabItem>
  <TabItem value="mac" label="macOS">Use Command + C to copy.</TabItem>
</Tabs>

<Tabs groupId="operating-systems">
  <TabItem value="win" label="Windows">Use Ctrl + V to paste.</TabItem>
  <TabItem value="mac" label="macOS">Use Command + V to paste.</TabItem>
</Tabs>

效果

Windows
macOS

Use Ctrl + C to copy.

Windows
macOS

Use Ctrl + V to paste.

对于具有相同组 ID 的所有选项卡组 groupId，可能的值不需要相同。如果一个选项卡组选择的值在具有相同值的另一个选项卡组中不存在 groupId，则具有缺失值的选项卡组不会更改其选项卡。您可以从下面的示例中看到这一点。尝试选择 Linux，上面的选项卡组不会改变。

语法示例 1：

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs groupId="operating-systems">
  <TabItem value="win" label="Windows">
    I am Windows.
  </TabItem>
  <TabItem value="mac" label="macOS">
    I am macOS.
  </TabItem>
  <TabItem value="linux" label="Linux">
    I am Linux.
  </TabItem>
</Tabs>

效果

Windows
macOS
Linux

I am Windows.

具有不同组 ID 的选项卡选择不会相互干扰：

语法示例 2：

<Tabs groupId="operating-systems">
  <TabItem value="win" label="Windows">Windows in windows.</TabItem>
  <TabItem value="mac" label="macOS">macOS is macOS.</TabItem>
</Tabs>

<Tabs groupId="non-mac-operating-systems">
  <TabItem value="win" label="Windows">Windows is windows.</TabItem>
  <TabItem value="unix" label="Unix">Unix is unix.</TabItem>
</Tabs>

效果

Windows
macOS

Windows in windows.

Windows
Unix

Windows is windows.

2. 代码块

文档中的代码块超级厉害 💪。

代码块标题

您可以通过 title 在语言后面添加键（在它们之间留一个空格）来向代码块添加标题。

语法示例 1：

    ```jsx title="/src/components/HelloCodeTitle.js"
    function HelloCodeTitle(props) {
      return <h1>Hello, {props.name}</h1>;
    }
    ```

效果

/src/components/HelloCodeTitle.js
function HelloCodeTitle(props) {
  return <h1>Hello, {props.name}</h1>;
}

语法高亮

代码块是使用 3 个反引号包裹的文本块。使用代码块的匹配语言元字符串，Docusaurus 将自动选择语法突出显示，由 Prism React Renderer 提供支持。默认情况下，我们使用的 Prism 语法高亮主题是 Palenight。您可以通过在 docusaurus.config.js prism themeConfig 中传递 theme 字段来将其更改为另一个主题。例如如果您更喜欢使用 dracula 突出显示主题：

docusaurus.config.js
module.exports = {
  themeConfig: {
    prism: {
      theme: require('prism-react-renderer/themes/dracula'),
    },
  },
};

支持的语言

默认情况下，Docusaurus 附带了常用语言的子集。

警告

一些流行语言，包括 Java、C#、PHP 在内，默认未启用。

要为任何其他 Prism 支持的语言添加语法突出显示，请在其他语言数组中定义它。

举个例子，如果你想要支持 PowerShell 语言的高亮：

docusaurus.config.js
module.exports = {
  // ...
  themeConfig: {
    prism: {
      additionalLanguages: ['powershell'],
    },
    // ...
  },
};

添加后 additionalLanguages，重新启动 Docusaurus。

如果您想为 Prism 尚不支持的语言添加突出显示，您可以 swizzle prism-include-languages：

npm
Yarn
pnpm

npm run swizzle @docusaurus/theme-classic prism-include-languages

yarn swizzle @docusaurus/theme-classic prism-include-languages

pnpm run swizzle @docusaurus/theme-classic prism-include-languages

它将 prism-include-languages.js 在您的 src/theme 文件夹中生成。您可以通过编辑添加对自定义语言的突出显示支持 prism-include-languages.js：

src/theme/prism-include-languages.js
const prismIncludeLanguages = (Prism) => {
  // ...

  additionalLanguages.forEach((lang) => {
    require(`prismjs/components/prism-${lang}`);
  });

  require('/path/to/your/prism-language-definition');

  // ...
};

您在编写自己的语言定义时可以参考Prism的官方语言定义。

突出显示

您可以使用带有 highlight-next-line、highlight-start、和 highlight-end 的注释来选择突出显示的行。

语法示例

    ```js
    function HighlightSomeText(highlight) {
      if (highlight) {
        return '这行被高亮了！';
      }

      return '这里不会';
    }

    function HighlightMoreText(highlight) {
      if (highlight) {
        return '这块被高亮了！';
      }

      return '这里不会';
    }
    ```
   

效果

   function HighlightSomeText(highlight) {
     if (highlight) {
       return '这行被高亮了！';
     }

     return '这里不会';
   }

   function HighlightMoreText(highlight) {
     if (highlight) {
       return '这块被高亮了！';
     }

     return '这里不会';
   }

3. 告示

除了基本的 Markdown 语法之外，我们还有一种特殊的警告语法，即用一组 3 个冒号包裹文本，后跟一个表示其类型的标签。

语法示例

:::note

这是一个 `备注` 告示效果演示

:::

:::tip

这是一个 `提示` 告示效果演示

:::

:::info

这是一个 `信息` 告示效果演示

:::

:::caution

这是一个 `警告` 告示效果演示

:::

:::danger

这是一个 `危险` 告示效果演示

:::

效果

备注

这是一个 备注 告示效果演示

提示

这是一个 提示 告示效果演示

信息

这是一个 信息 告示效果演示

警告

这是一个 警告 告示效果演示

危险

这是一个 危险 告示效果演示

如果您使用Prettier格式化 Markdown 文件，Prettier 可能会将您的代码自动格式化为无效的警告语法。为了避免此问题，请在开始和结束指令周围添加空行。这也是为什么我们在这里展示的示例的内容周围都有空行。

指定标题

您还可以指定一个可选标题，只需在该告示的类型标签后加上你指定的标题即可。

语法示例

:::tip玛卡巴卡

这是一个 `提示` 告示 `指定标题` 的效果演示

:::

效果

玛卡巴卡

这是一个 提示 告示 指定标题的效果演示

告示中使用 MDX

您也可以在告示中使用 MDX！

语法示例

import Tabs from '@theme/Tabs';

import TabItem from '@theme/TabItem';

:::tip

Use tabs in admonitions

<Tabs>
  <TabItem value="apple" label="Apple">This is an apple 🍎</TabItem>
  <TabItem value="orange" label="Orange">This is an orange 🍊</TabItem>
  <TabItem value="banana" label="Banana">This is a banana 🍌</TabItem>
</Tabs>

:::

效果

提示

Use tabs in admonitions

Apple
Orange
Banana

This is an apple 🍎

在JSX中使用告示

在 Markdown 之外，您可以使用该@theme/Admonition组件来获得相同的输出。

MyReactPage.jsx
import Admonition from '@theme/Admonition';

export default function MyReactPage() {
  return (
    <div>
      <Admonition type="info">
        <p>Some information</p>
      </Admonition>
    </div>
  );
}

除了可以使用默认的 note, tip, danger, info, caution 5 种告示外，你也可以选择性地以 JSX 元素或者字符串的形式指定一个图标或者一个标题：

语法示例

MyReactPage.jsx
<Admonition type="tip" icon="💡" title="你可知道...">
  <p>
    使用插件为项目中最常用的JSX元素引入较短的语法。
  </p>
</Admonition>

定制告示

告示有两种可能的定制：解析和渲染。

自定义渲染

可以自定义如何通过调配呈现每个单独的告示类型。一般只需要一个简单的包装组件就可以达到想要的效果。例如，在下面的示例中，我们仅将图标替换为 info 告示。

src/theme/Admonition.js
import React from 'react';
import Admonition from '@theme-original/Admonition';
import MyIcon from '@site/static/img/info.svg';

export default function AdmonitionWrapper(props) {
  if (props.type !== 'info') {
    return <Admonition {...props} />;
  }
  return <Admonition icon={<MyIcon />} {...props} />;
}

自定义解析

告示是通过 Remark 插件实现的，这个插件被设计为可配置的。要为特定内容插件（文档、博客、页面）自定义 Remark 插件，请通过 admonitions 键传递选项。

docusaurus.config.js
module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          admonitions: {
            tag: ':::',
            keywords: ['note', 'tip', 'info', 'caution', 'danger'],
          },
        },
      },
    ],
  ],
};

插件接受两个选项：

tag：包含警告的标签。默认为:::。
keywords: 可用作警告类型的关键字数组。请注意，如果你覆盖了这个选项，就不会应用默认值。

该 keyword 将作为 Admonition 组件的 type 道具传递。如果你注册了默认值之外的类型，你就需要负责提供它们的实现，包括容器的样式、图标、默认标题文本等。您通常需要弹出 @theme/Admonition 组件，以便您可以重新使用与其他类型相同的基础设施。

1. 选项卡​

设置默认选项卡​

同步选项卡​

2. 代码块​

代码块标题​

语法高亮​

支持的语言​

突出显示​

3. 告示​

指定标题​

告示中使用 MDX​

在JSX中使用告示​

定制告示​

自定义渲染​

自定义解析​

文章目录

1. 选项卡

设置默认选项卡

同步选项卡

2. 代码块

代码块标题

语法高亮

支持的语言

突出显示

3. 告示

指定标题

告示中使用 MDX

在JSX中使用告示

定制告示

自定义渲染

自定义解析