Docusaurus 中 Markdown 代码块的高级功能解析-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00030/article/details/148324174

Docusaurus 中 Markdown 代码块的高级功能解析

docusaurus Easy to maintain open source documentation websites. 项目地址: https://gitcode.com/gh_mirrors/do/docusaurus

前言

在现代技术文档中，代码展示是不可或缺的重要组成部分。Docusaurus 作为一款优秀的文档工具，提供了丰富而强大的代码块功能，让开发者能够以专业、美观的方式展示代码片段。本文将全面解析 Docusaurus 中 Markdown 代码块的各种高级功能，帮助您充分利用这些特性提升文档质量。

基础代码块语法

Docusaurus 使用标准的 Markdown 代码块语法，由三反引号包裹代码内容：

```javascript
console.log('Hello Docusaurus');
```

这种基础语法已经能够满足简单的代码展示需求，但 Docusaurus 提供了更多增强功能。

代码块标题功能

为代码块添加标题可以显著提升代码示例的可读性和组织性。在语言标识符后添加 title 属性即可：

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

效果展示：

function Welcome(props) {
  return <h1>Hello, {props.name}</h1>;
}

标题不仅提供了上下文信息，还能帮助读者快速定位相关代码文件。

语法高亮功能

Docusaurus 使用 Prism 作为语法高亮引擎，支持多种编程语言的自动高亮显示。只需在代码块开头指定正确的语言标识符：

```python
def greet(name):
    print(f"Hello, {name}!")
```

主题定制

默认使用 Palenight 主题，但可以通过配置更改为其他 Prism 主题：

import {themes as prismThemes} from 'prism-react-renderer';

export default {
  themeConfig: {
    prism: {
      theme: prismThemes.dracula,  // 更改为 Dracula 主题
    },
  },
};

语言支持扩展

虽然 Docusaurus 默认支持常见语言，但如需添加如 PowerShell 等语言支持：

export default {
  themeConfig: {
    prism: {
      additionalLanguages: ['powershell'],
    },
  },
};

修改配置后需要重启 Docusaurus 使更改生效。

代码行高亮功能

使用注释高亮

Docusaurus 提供了特殊的注释语法来高亮特定代码行：

```javascript
function example() {
  // highlight-next-line
  console.log('这行会被高亮显示');
  
  // highlight-start
  const a = 1;
  const b = 2;
  // highlight-end
  return a + b;
}
```

支持多种注释风格：

C 风格：// 和 /* */
JSX 风格：{/* */}
Bash 风格：#
HTML 风格：

使用元数据高亮

也可以在代码块语言标识后直接指定高亮行：

```jsx {1,3-5}
import React from 'react';

function Component() {
  return <div>Highlighted</div>;
}
```

行号显示功能

启用行号可以帮助代码讲解和问题定位：

```js showLineNumbers
function add(a, b) {
  return a + b;
}
```

还可以自定义起始行号：

```js showLineNumbers=10
// 从第10行开始编号
function multiply(a, b) {
  return a * b;
}
```

交互式代码编辑器

Docusaurus 支持创建可交互的代码编辑器，需要安装额外插件：

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

然后在配置中启用：

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

使用方式：

```jsx live
function Counter() {
  const [count, setCount] = useState(0);
  return (
    <button onClick={() => setCount(c => c + 1)}>
      Clicked {count} times
    </button>
  );
}
```

高级技巧

自定义高亮样式

可以通过 CSS 自定义高亮行的外观：

:root {
  --docusaurus-highlighted-code-line-bg: rgb(72, 77, 91);
}

[data-theme='dark'] {
  --docusaurus-highlighted-code-line-bg: rgb(100, 100, 100);
}

多语言代码块

对于需要展示多种语言实现的场景，可以使用 Tabs 组件：

<Tabs>
  <TabItem value="js" label="JavaScript">
    ```js
    console.log('Hello from JS');
    ```
  </TabItem>
  <TabItem value="py" label="Python">
    ```python
    print('Hello from Python')
    ```
  </TabItem>
</Tabs>