Version: 2.0.0-beta.3

代码块

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

代码标题#

您可以在语言后添加 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 技术规范。

```jsxconsole.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 自带部分常用语言的支持。

注意

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

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

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

docusaurus.config.js

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

如果您想添加 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 来选择要高亮的行。

```jsxfunction 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 livefunction 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>  );}```

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

实时编辑器

结果

SyntaxError: Unexpected token (1:8)
1 : return ()
            ^

导入#

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 组件了：

实时编辑器

结果

SyntaxError: Unexpected token (1:8)
1 : return ()
            ^

支持多语言的代码块#

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

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

下方是在文档中显示多编程语言代码选项卡的示例。注意，我们有意在语言块的上下方留白。这当前是 MDX 的限制，您需要在 Markdown 语法上下留几行空，让 MDX 解析器知晓这是 Markdown 语法而非 JSX 内容。

import Tabs from '@theme/Tabs';import TabItem from '@theme/TabItem';
<Tabs  defaultValue="js"  values={[    { label: 'JavaScript', value: 'js', },    { label: 'Python', value: 'py', },    { label: 'Java', value: 'java', },  ]}><TabItem value="js">
```jsfunction helloWorld() {  console.log('Hello, world!');}```
</TabItem><TabItem value="py">
```pydef hello_world():  print 'Hello, world!'```
</TabItem><TabItem value="java">
```javaclass 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");  }}

若您觉得上述流程过于繁琐，您可以实现自己的 <MultiLanguageCode /> 抽象。我们可能会在将来实现一个抽象以便您使用。

若您有多个多语言代码选项卡，且您希望在多个选项卡实例中同步选择项，请参考同步选项卡选择章节。