Version: 2.0.0-beta.9

代码块

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

代码标题

您可以在语言后添加 title 键（在后面添加空格）来添加标题。

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

/src/components/HelloCodeTitle.js

function HelloCodeTitle(props) {
  return <h1>你好，{props.name}</h1>;
}

语法高亮

代码块是使用 3 个反引号包裹的文本块。您可参阅 MDX 技术规范。

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

在代码块中使用相应语言的标签，Docusaurus 将自动使用 Prism React Renderer 为您实现语法高亮。

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

Theming

我们默认使用的语法高亮主题是 Palenight。您可以在 prism 传递 theme 字段，并放入 docusaurus.config.js 中的 themeConfig 来更改主题。

举个例子，如果您喜欢 dracula 高亮主题：

docusaurus.config.js

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

Supported Languages

默认情况下，Docusaurus 自带部分常用语言的支持。

caution

一些如 Java、C# 或 PHP 在内的流行语言默认未启用。

要添加其他Prism 所支持语言的代码高亮，请在额外语言数组中定义。

举个例子，假设您想要添加 powershell 语言的支持：

docusaurus.config.js

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

After adding additionalLanguages, restart Docusaurus.

如果您想添加 Prism 所不支持语言的语法高亮功能，您可变换（Swizzle） prism-include-languages：

npm
Yarn

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

yarn 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}`); // eslint-disable-line
  });

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

  // ...
};

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

行高亮

您可在语言源标签后指定行数范围（在语言后添加空格）来强调特定代码。

```jsx {3}
function HighlightSomeText(highlight) {
  if (highlight) {
    return '这句被高亮了！';
  }

  return '这句没有';
}
```

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

  return '这句没有';
}

Docusaurus 以向高亮行添加 docusaurus-highlight-code-line 类的方式来达成此效果。您需要在 CSS 中定义您自己的样式，其通常位于 src/css/custom.css，而且其中的自定义背景颜色也依赖您所选的语法高亮主题。下方的颜色适用于默认的语法高亮主题（Palenight）。若您使用其他主题的话，您也需要修改此颜色。

/src/css/custom.css

.docusaurus-highlight-code-line {
  background-color: rgb(72, 77, 91);
  display: block;
  margin: 0 calc(-1 * var(--ifm-pre-padding));
  padding: 0 var(--ifm-pre-padding);
}

/* 若您在暗色模式中使用了不同的语法高亮主题。 */
html[data-theme='dark'] .docusaurus-highlight-code-line {
  /* Color which works with dark mode syntax highlighting theme */
  background-color: rgb(100, 100, 100);
}

Multiple line highlighting

要高亮多行内容，请使用半角逗号来分隔行号，或使用范围语法来选择多行代码块。此功能使用 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;
```

import React from 'react';

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

  return <div>Foo</div>;
}

export default MyComponent;

Highlighting with comments

您也可以使用 highlight-next-line、highlight-start 和 highlight-end 来选择要高亮的行。

```jsx
function HighlightSomeText(highlight) {
  if (highlight) {
    // highlight-next-line
    return '这句被高亮了！';
  }

  return '这里不会';
}

function HighlightMoreText(highlight) {
  // highlight-start
  if (highlight) {
    return '这片区域被高亮了！';
  }
  // highlight-end

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

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

  return '这里不会';
}

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

  return '这里不会';
}

支持的注释语法：

语言	语法
JavaScript	`/* ... */` 及 `// ...`
JSX	`{/* ... */}`
Python	`# ...`
HTML	`<!-- ... -->`

若有暂不支持的语法，我们很乐意添加！我们欢迎合并请求。

交互式代码编辑器

（由 React Live 驱动）

您可使用 @docusaurus/theme-live-codeblock 插件创建可交互的代码编辑器。

首先，添加插件至您的网站。

npm
Yarn

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

yarn add @docusaurus/theme-live-codeblock

您还需要在 docusaurus.config.js 中添加插件。

module.exports = {
  // ...
  themes: ['@docusaurus/theme-live-codeblock'],
  // ...
};

要使用此插件，请先创建代码块，同时在语言源标签中附加上 live 标签。

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

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

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

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

此代码块将渲染为可交互的代码编辑器。代码更改将实时显示在预览区内。

实时编辑器

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

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

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

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

function Clock(props) {
  const [date, setDate] = useState(new Date());
  useEffect(() => {
    var 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

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

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

src/theme/ReactLiveScope/index.js

import React from 'react';

const ButtonExample = (props) => (
  <button
    {...props}
    style={{
      backgroundColor: 'white',
      border: 'solid red',
      borderRadius: 20,
      padding: 10,
      cursor: 'pointer',
      ...props.style,
    }}
  />
);

// 在此处添加您需要的 react-live 导入
const ReactLiveScope = {
  React,
  ...React,
  ButtonExample,
};

export default ReactLiveScope;

现在，您可使用 ButtonExample 组件了：

实时编辑器

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

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

结果

支持多语言的代码块

借由 MDX，您可轻松在文档内创建可交互的组件。举个例子，您可以编写适用于多款编程语言的示例代码，并使用标签页组件进行切换。

我们并没有实现多语言代码块支持的专用组件，而是在经典主题中编写了通用的选项卡组件，以便您在其他非代码的场景中使用。

下方是在文档中显示多编程语言代码选项卡的示例。注意，我们有意在语言块的上下方留白。这当前是 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('Hello, world!');
}
```

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

```py
def hello_world():
  print 'Hello, world!'
```

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

```java
class HelloWorld {
  public static void main(String args[]) {
    System.out.println("Hello, World");
  }
}
```

</TabItem>
</Tabs>

And you will get the following:

JavaScript
Python
Java

function helloWorld() {
  console.log('Hello, world!');
}

def hello_world():
  print 'Hello, world!'

class HelloWorld {
  public static void main(String args[]) {
    System.out.println("Hello, World");
  }
}

If you have multiple of these multi-language code tabs, and you want to sync the selection across the tab instances, refer to the Syncing tab choices section.

Docusaurus npm2yarn remark plugin

Displaying CLI commands in both NPM and Yarn is a very common need, for example:

npm
Yarn

npm install @docusaurus/remark-plugin-npm2yarn

yarn add @docusaurus/remark-plugin-npm2yarn

Docusaurus provides such a utility out of the box, freeing you from using the Tabs component every time. To enable this feature, first install the @docusaurus/remark-plugin-npm2yarn package as above, and then in docusaurus.config.js, for the plugins where you need this feature (doc, blog, pages, etc.), register it in the remarkPlugins option. (See Docs configuration for more details on configuration format)

docusaurus.config.js

module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          remarkPlugins: [
            [require('@docusaurus/remark-plugin-npm2yarn'), {sync: true}],
          ],
        },
        pages: {
          remarkPlugins: [require('@docusaurus/remark-plugin-npm2yarn')],
        },
        blog: {
          // ...
        },
      },
    ],
  ],
};

And then use it by adding the npm2yarn key to the code block:

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

Using the {sync: true} option would make all tab choices synced. Because the choice is stored under the same namespace npm2yarn, different npm2yarn plugin instances would also sync their choices.

代码标题​

语法高亮​

Theming​

Supported Languages​

caution

行高亮​

Multiple line highlighting​

Highlighting with comments​

交互式代码编辑器​

导入​

react-live 及导入警告

支持多语言的代码块​

Docusaurus npm2yarn remark plugin​

代码标题

语法高亮

Theming

Supported Languages

行高亮

Multiple line highlighting

Highlighting with comments

交互式代码编辑器

导入

支持多语言的代码块

Docusaurus npm2yarn remark plugin