代码块

文档中的代码块功能超级强大 💪。

代码块标题

你可以在语言声明之后添加一个 title 键，为代码块添加标题（请在它们之间留一个空格）。

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

http://localhost:3000

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

语法高亮

代码块是由三反引号字符串包裹的文本块。你可以查阅这份 MDX 规范来了解更多细节。

```js
console.log('每个代码仓库都应该有一个吉祥物。');
```

为你的代码块使用匹配的语言元字符串，道格龙（Docusaurus）将自动应用语法高亮，这由 Prism React Renderer 提供支持。

http://localhost:3000

console.log('每个代码仓库都应该有一个吉祥物。');

主题化

默认情况下，我们使用的 Prism 语法高亮主题是 Palenight。你可以通过在 docusaurus.config.js 的 themeConfig 中，为 prism 字段传递 theme 来更换主题。

例如，如果你更喜欢使用 dracula 高亮主题：

docusaurus.config.js
import {themes as prismThemes} from 'prism-react-renderer';

export default {
  themeConfig: {
    prism: {
      theme: prismThemes.dracula,
    },
  },
};

因为 Prism 主题只是一个 JS 对象，如果你对默认主题不满意，也可以编写自己的主题。道格龙（Docusaurus）增强了 github 和 vsDark 主题以提供更丰富的高亮效果，你可以查看我们为亮色和暗色代码块主题的实现。

支持的语言

默认情况下，道格龙（Docusaurus）仅捆绑了常用语言的一个子集。

warning

一些流行语言，如 Java、C# 或 PHP，默认并未启用。

要为其他任何 Prism 支持的语言添加语法高亮，请在 additionalLanguages 数组中定义它。

note

每个附加语言都必须是一个有效的 Prism 组件名称。例如，Prism 会将语言 cs 映射到 csharp，但只有 prism-csharp.js 作为组件存在，所以你需要使用 additionalLanguages: ['csharp']。你可以查看 node_modules/prismjs/components 目录来找到所有可用的组件（语言）。

例如，如果你想为 PowerShell 语言添加高亮：

docusaurus.config.js
export default {
  // ...
  themeConfig: {
    prism: {
      additionalLanguages: ['powershell'],
    },
    // ...
  },
};

添加 additionalLanguages 后，请重启道格龙（Docusaurus）服务。

如果你想为 Prism 尚不支持的语言添加高亮，你可以 swizzle prism-include-languages：

npm
Yarn
pnpm
Bun

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

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

这将在你的 src/theme 文件夹中生成 prism-include-languages.js 文件。你可以通过编辑 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 的官方语言定义。

添加自定义语言定义时，你不需要将该语言添加到 additionalLanguages 配置数组中，因为道格龙（Docusaurus）只在 Prism 提供的语言中查找 additionalLanguages 字符串。在 prism-include-languages.js 中添加语言导入就足够了。

段落高亮

使用注释进行高亮

你可以使用带有 highlight-next-line、highlight-start 和 highlight-end 的注释来选择需要高亮的行。

```js
function HighlightSomeText(highlight) {
  if (highlight) {
    // highlight-next-line
    return '这行文本被高亮了！';
  }

  return '没有内容被高亮';
}

function HighlightMoreText(highlight) {
  // highlight-start
  if (highlight) {
    return '这个范围内的文本被高亮了！';
  }
  // highlight-end

  return '没有内容被高亮';
}
```

http://localhost:3000

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

  return '没有内容被高亮';
}

function HighlightMoreText(highlight) {
  if (highlight) {
    return '这个范围内的文本被高亮了！';
  }

  return '没有内容被高亮';
}

支持的注释语法：

风格	语法
C 风格	`/* ... */` 和 `// ...`
JSX 风格	`{/* ... */}`
Bash 风格	`# ...`
HTML 风格	`<!-- ... -->`

我们会尽力根据语言推断使用哪种注释风格，并默认允许所有注释风格。如果当前有不支持的注释风格，我们乐于添加它们！欢迎提交 Pull Request。请注意，不同的注释风格没有语义上的区别，只有它们的内容有。

你可以在你的 src/css/custom.css 文件中为你高亮的代码行设置自定义的背景色，以便更好地适应你选择的语法高亮主题。下面给出的颜色适用于默认的高亮主题（Palenight），所以如果你使用其他主题，你需要相应地调整颜色。

/src/css/custom.css
:root {
  --docusaurus-highlighted-code-line-bg: rgb(72, 77, 91);
}

/* 如果你的暗黑模式有不同的语法高亮主题 */
[data-theme='dark'] {
  /* 适用于暗黑模式语法高亮主题的颜色 */
  --docusaurus-highlighted-code-line-bg: rgb(100, 100, 100);
}

如果你还需要以其他方式为高亮的代码行设置样式，你可以针对 theme-code-block-highlighted-line 这个 CSS 类进行设置。

使用元数据字符串进行高亮

你也可以在语言元字符串中指定高亮的行范围（在语言后留一个空格）。要高亮多行，可以用逗号分隔行号，或使用范围语法来选择一个行块。此功能使用了 parse-number-range 库，你可以在他们的项目详情中找到更多语法。

```jsx {1,4-6,11}
import React from 'react';

function MyComponent(props) {
  if (props.isBar) {
    return <div>Bar</div>;
  }

  return <div>Foo</div>;
}

export default MyComponent;
```

http://localhost:3000

import React from 'react';

function MyComponent(props) {
  if (props.isBar) {
    return <div>Bar</div>;
  }

  return <div>Foo</div>;
}

export default MyComponent;

优先使用注释

在可能的情况下，优先使用注释进行高亮。通过在代码中内联高亮，当你的代码块变长时，你就不必手动计算行数。如果你添加或删除行，你也不必调整你的行范围。

- ```jsx {3}
+ ```jsx {4}
  function HighlightSomeText(highlight) {
    if (highlight) {
+     console.log('找到高亮文本');
      return '这行文本被高亮了！';
    }

    return '没有内容被高亮';
  }
  ```

下面，我们将介绍如何扩展魔法注释系统来定义自定义指令及其功能。只有在没有高亮元字符串存在时，魔法注释才会被解析。

自定义魔法注释

// highlight-next-line 和 // highlight-start 等被称为"魔法注释"，因为它们会被解析和移除，它们的目的是为下一行或由开始和结束注释对包围的区域添加元数据。

你可以通过主题配置声明自定义的魔法注释。例如，你可以注册另一个魔法注释，它会添加一个 code-block-error-line 类名：

docusaurus.config.js
src/css/custom.css
myDoc.md

export default {
  themeConfig: {
    prism: {
      magicComments: [
        // 别忘了也要扩展默认的高亮类名！
        {
          className: 'theme-code-block-highlighted-line',
          line: 'highlight-next-line',
          block: {start: 'highlight-start', end: 'highlight-end'},
        },
        {
          className: 'code-block-error-line',
          line: 'This will error',
        },
      ],
    },
  },
};

.code-block-error-line {
  background-color: #ff000020;
  display: block;
  margin: 0 calc(-1 * var(--ifm-pre-padding));
  padding: 0 var(--ifm-pre-padding);
  border-left: 3px solid #ff000080;
}

在 JavaScript 中，尝试访问 `null` 的属性会报错。

```js
const name = null;
// This will error
console.log(name.toUpperCase());
// Uncaught TypeError: Cannot read properties of null (reading 'toUpperCase')
```

http://localhost:3000

在 JavaScript 中，尝试访问 null 的属性会报错。

const name = null;
// This will error
console.log(name.toUpperCase());
// Uncaught TypeError: Cannot read properties of null (reading 'toUpperCase')

如果你在元字符串中使用数字范围（即 {1,3-4} 语法），道格龙（Docusaurus）将应用第一个 magicComments 条目的类名。默认情况下，这个类名是 theme-code-block-highlighted-line，但如果你更改了 magicComments 配置并使用了不同的条目作为第一个，元字符串范围的含义也会随之改变。

你可以使用 magicComments: [] 来禁用默认的行高亮注释。如果没有魔法注释配置，但道格龙（Docusaurus）遇到了一个包含元字符串范围的代码块，它将会报错，因为没有类名可以应用——毕竟，高亮类名本身就是一个魔法注释条目。

每个魔法注释条目将包含三个键：className（必需），line（应用于紧接着的下一行），或 block（包含 start 和 end，应用于由两个注释包围的整个块）。

使用 CSS 来定位类已经可以做很多事情了，但你可以通过 swizzling 来释放这个功能的全部潜力。

npm
Yarn
pnpm
Bun

npm run swizzle @docusaurus/theme-classic CodeBlock/Line

yarn swizzle @docusaurus/theme-classic CodeBlock/Line

pnpm run swizzle @docusaurus/theme-classic CodeBlock/Line

bun run swizzle @docusaurus/theme-classic CodeBlock/Line

Line 组件将接收类名列表，基于这些类名，你可以有条件地渲染不同的标记。

行号显示

你可以在语言元字符串中使用 showLineNumbers 关键字来为你的代码块启用行号显示（别忘了在关键字前加一个空格）。

```jsx showLineNumbers
import React from 'react';

export default function MyComponent(props) {
  return <div>Foo</div>;
}
```

http://localhost:3000

import React from 'react';

export default function MyComponent(props) {
  return <div>Foo</div>;
}

默认情况下，计数器从行号 1 开始。为了提高可读性，可以通过传递一个自定义的起始计数值来分割大型代码块：

```jsx showLineNumbers=3
export default function MyComponent(props) {
  return <div>Foo</div>;
}
```

http://localhost:3000

export default function MyComponent(props) {
  return <div>Foo</div>;
}

交互式代码编辑器

（由 React Live 提供支持）

你可以使用 @docusaurus/theme-live-codeblock 插件创建一个交互式代码编辑器。首先，将该插件添加到你的 package.json 中。

npm
Yarn
pnpm
Bun

npm install --save @docusaurus/theme-live-codeblock

yarn add @docusaurus/theme-live-codeblock

pnpm add @docusaurus/theme-live-codeblock

bun add @docusaurus/theme-live-codeblock

你还需要将该插件添加到你的 docusaurus.config.js 中。

export default {
  // ...
  themes: ['@docusaurus/theme-live-codeblock'],
  // ...
};

要使用该插件，创建一个代码块，并在语言元字符串后附加 live。

```jsx live
function Clock(props) {
  const [date, setDate] = useState(new Date());
  useEffect(() => {
    const timerID = setInterval(() => tick(), 1000);

    return function cleanup() {
      clearInterval(timerID);
    };
  });

  function tick() {
    setDate(new Date());
  }

  return (
    <div>
      <h2>现在是 {date.toLocaleTimeString()}.</h2>
    </div>
  );
}
```

该代码块将被渲染为一个交互式编辑器。对代码的更改将实时反映在结果面板上。

http://localhost:3000

function Clock(props) {
  const [date, setDate] = useState(new Date());
  useEffect(() => {
    const timerID = setInterval(() => tick(), 1000);

    return function cleanup() {
      clearInterval(timerID);
    };
  });

  function tick() {
    setDate(new Date());
  }

  return (
    <div>
      <h2>现在是 {date.toLocaleTimeString()}.</h2>
    </div>
  );
}

导入

react-live 和导入

无法直接从 react-live 代码编辑器中导入组件，你必须预先定义可用的导入。

默认情况下，所有 React 的导入都是可用的。如果你需要更多可用的导入，可以 swizzle react-live 的作用域：

npm
Yarn
pnpm
Bun

npm run swizzle @docusaurus/theme-live-codeblock ReactLiveScope -- --eject

yarn swizzle @docusaurus/theme-live-codeblock ReactLiveScope --eject

pnpm run swizzle @docusaurus/theme-live-codeblock ReactLiveScope --eject

bun run swizzle @docusaurus/theme-live-codeblock ReactLiveScope --eject

src/theme/ReactLiveScope/index.js
import React from 'react';

// 定义一个可以在实时编辑器中使用的按钮组件
const ButtonExample = (props) => (
  <button
    {...props}
    style={{
      backgroundColor: 'white',
      color: 'black',
      border: 'solid red',
      borderRadius: 20,
      padding: 10,
      cursor: 'pointer',
      ...props.style,
    }}
  />
);

// 在此处添加你需要的 react-live 导入
const ReactLiveScope = {
  React,
  ...React,
  ButtonExample, // 将你的组件添加到作用域中
};

export default ReactLiveScope;

现在 ButtonExample 组件就可以使用了：

http://localhost:3000

function MyPlayground(props) {
  return (
    <div>
      <ButtonExample onClick={() => alert('你好！')}>点我</ButtonExample>
    </div>
  );
}

命令式渲染 (noInline)

当你的代码跨越多个组件或变量时，应使用 noInline 选项以避免错误。

```jsx live noInline
const project = '道格龙（Docusaurus）';

const Greeting = () => <p>你好 {project}!</p>;

render(<Greeting />);
```

与普通的交互式代码块不同，当使用 noInline 时，React Live 不会将你的代码包装在一个内联函数中来渲染它。

你需要在代码的末尾显式调用 render() 来显示输出。

http://localhost:3000

const project = "道格龙（Docusaurus）";

const Greeting = () => (
  <p>你好 {project}!</p>
);

render(
  <Greeting />
);

在代码块中使用 JSX 标记

Markdown 中的代码块始终将其内容保留为纯文本，这意味着你不能做这样的事情：

type EditUrlFunction = (params: {
  // 这不会变成一个链接（这是合理的！）
  version: <a href="/docusaurus/versioning">版本</a>;
  versionDocsDirPath: string;
  docPath: string;
  permalink: string;
  locale: string;
}) => string | undefined;

如果你想嵌入 HTML 标记，如锚链接或粗体文本，你可以使用 <pre> 标签、<code> 标签或 <CodeBlock> 组件。

<pre>
  <b>输入：</b>1 2 3 4{'\n'}
  <b>输出：</b>"366300745"{'\n'}
</pre>

http://localhost:3000

输入：1 2 3 4
输出："366300745"

MDX 对空白不敏感

MDX 的行为与 JSX 一致：换行符，即使在 <pre> 内部，也会被转换为空格。你必须显式地写入换行符 \n 才能使其被打印出来。

warning

语法高亮仅适用于纯字符串。道格龙（Docusaurus）不会尝试解析包含 JSX 子节点的代码块内容。

多语言支持代码块

借助 MDX，你可以轻松地在文档中创建交互式组件，例如，用多种编程语言显示代码，并使用标签页组件在它们之间切换。

我们没有为多语言支持代码块实现一个专门的组件，而是在经典主题中实现了一个通用的 <Tabs> 组件，这样你也可以将它用于其他非代码场景。

下面的示例展示了如何在你的文档中拥有多语言代码标签页。请注意，每个语言块上方和下方的空行是有意为之的。这是 MDX 的一个当前限制：你必须在 Markdown 语法周围留出空行，MDX 解析器才能知道它是 Markdown 语法而不是 JSX。

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

<Tabs>
<TabItem value="js" label="JavaScript">

```js
function helloWorld() {
  console.log('你好，世界！');
}
```

</TabItem>
<TabItem value="py" label="Python">

```py
def hello_world():
  print("你好，世界！")
```

</TabItem>
<TabItem value="java" label="Java">

```java
class HelloWorld {
  public static void main(String args[]) {
    System.out.println("你好，世界！");
  }
}
```

</TabItem>
</Tabs>

然后你会得到如下效果：

http://localhost:3000

JavaScript
Python
Java

function helloWorld() {
  console.log('你好，世界！');
}

def hello_world():
  print("你好，世界！")

class HelloWorld {
  public static void main(String args[]) {
    System.out.println("你好，世界！");
  }
}

如果你有多个这样的多语言代码标签页，并且希望在不同实例之间同步选项，请参阅同步标签页选择部分。

道格龙（Docusaurus） npm2yarn remark 插件

同时用 npm 和 Yarn 显示 CLI 命令是一个非常普遍的需求，例如：

npm
Yarn
pnpm
Bun

npm install @docusaurus/remark-plugin-npm2yarn

yarn add @docusaurus/remark-plugin-npm2yarn

pnpm add @docusaurus/remark-plugin-npm2yarn

bun add @docusaurus/remark-plugin-npm2yarn

道格龙（Docusaurus）为此提供了一个开箱即用的工具，让你不必每次都使用 Tabs 组件。要启用此功能，首先如上安装 @docusaurus/remark-plugin-npm2yarn 包，然后在 docusaurus.config.js 中，为你需要此功能的插件（doc、blog、pages 等）在 remarkPlugins 选项中注册它。（有关配置格式的更多详细信息，请参阅文档配置）

docusaurus.config.js
export default {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          remarkPlugins: [
            [require('@docusaurus/remark-plugin-npm2yarn'), {sync: true}],
          ],
        },
        pages: {
          remarkPlugins: [require('@docusaurus/remark-plugin-npm2yarn')],
        },
        blog: {
          remarkPlugins: [
            [
              require('@docusaurus/remark-plugin-npm2yarn'),
              {converters: ['pnpm']},
            ],
          ],
          // ...
        },
      },
    ],
  ],
};

然后通过向代码块添加 npm2yarn 关键字来使用它：

```bash npm2yarn
npm install @docusaurus/remark-plugin-npm2yarn
```

配置

选项	类型	默认值	描述
`sync`	`boolean`	`false`	是否在所有代码块之间同步所选的转换器。
`converters`	`array`	`'yarn'`, `'pnpm'`	要使用的转换器列表。转换器的顺序很重要，因为第一个将被用作默认选项。

在 JSX 中使用

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

import CodeBlock from '@theme/CodeBlock';

export default function MyReactPage() {
  return (
    <div>
      <CodeBlock
        language="jsx"
        title="/src/components/HelloCodeTitle.js"
        showLineNumbers>
        {`function HelloCodeTitle(props) {
  return <h1>你好, {props.name}</h1>;
}`}
      </CodeBlock>
    </div>
  );
}

http://localhost:3000

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

接受的属性(props)是 language、title 和 showLineNumbers，其方式与你编写 Markdown 代码块时相同。

虽然不鼓励，但你也可以传递一个 metastring 属性，如 metastring='{1-2} title="/src/components/HelloCodeTitle.js" showLineNumbers'，这也是 Markdown 代码块在底层处理的方式。但是，我们建议你使用注释来高亮行。

正如之前所述，只有当子节点是简单字符串时，才会应用语法高亮。

代码块标题​

语法高亮​

主题化​

支持的语言​

段落高亮​

使用注释进行高亮​

使用元数据字符串进行高亮​

自定义魔法注释​

行号显示​

交互式代码编辑器​

导入​

命令式渲染 (noInline)​

在代码块中使用 JSX 标记​

多语言支持代码块​

道格龙（Docusaurus） npm2yarn remark 插件​

配置​

在 JSX 中使用​

代码块标题

语法高亮

主题化

支持的语言

段落高亮

使用注释进行高亮

使用元数据字符串进行高亮

自定义魔法注释

行号显示

交互式代码编辑器

导入

命令式渲染 (noInline)

在代码块中使用 JSX 标记

多语言支持代码块

道格龙（Docusaurus） npm2yarn remark 插件

配置

在 JSX 中使用