版本：Canary 🚧

代码块

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

代码标题

您可以通过在语言之后添加title键来为代码块添加标题(在它们之间留下空格)。

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

http://localhost:3000

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

语法高亮显示

代码块是由 3 个反引号组成的字符串包围的文本块。您可以查看此参考以了解 MDX 的规范。

```js
console.log("Every repo must come with a mascot.");
```

为你的代码块使用匹配的语言元字符串，Docusaurus 将自动选择语法高亮，由Prism React Renderer提供支持。

http://localhost:3000

console.log("Every repo must come with a mascot.");

主题

默认情况下，我们使用的 Prism语法高亮主题是Palenight。你可以通过将prism中的theme字段作为docusaurus.config.js中的themeConfig将其更改为另一个主题。

例如，如果你喜欢使用dracula突出主题:

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

因为 Prism 主题只是一个 JS 对象，如果您对默认的不满意，也可以编写自己的主题。Docusaurus 增强了github和vsDark主题，以提供更丰富的亮点，您可以查看我们的light和dark代码块主题的实现。

支持的语言

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

警告

一些流行的语言，如 Java、c#或 PHP，默认情况下是不启用的。

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

备注

Each additional language has to be a valid Prism component name. For example, Prism would map the language cs to csharp, but only prism-csharp.js exists as a component, so you need to use additionalLanguages: ['csharp']. You can look into node_modules/prismjs/components to find all components (languages) available.

例如，如果你想为 PowerShell 语言添加高亮显示:

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

添加additionalLanguages后，重启 Docusaurus。

如果你想为 Prism 不支持的语言添加高亮显示，你可以点击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

It will produce prism-include-languages.js in your src/theme folder. You can add highlighting support for custom languages by editing 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");

  // ...
};

You can refer to Prism's official language definitions when you are writing your own language definitions.

When adding a custom language definition, you do not need to add the language to the additionalLanguages config array, since Docusaurus only looks up the additionalLanguages strings in languages that Prism provides. Adding the language import in prism-include-languages.js is sufficient.

行高亮显示

用注释高亮显示

You can use comments with highlight-next-line, highlight-start, and highlight-end to select which lines are highlighted.

```js
function HighlightSomeText(highlight) {
  if (highlight) {
    // highlight-next-line
    return "This text is highlighted!";
  }

  return "Nothing highlighted";
}

function HighlightMoreText(highlight) {
  // highlight-start
  if (highlight) {
    return "This range is highlighted!";
  }
  // highlight-end

  return "Nothing highlighted";
}
```

http://localhost:3000

function HighlightSomeText(highlight) {
  if (highlight) {
    return "This text is highlighted!";
  }

  return "Nothing highlighted";
}

function HighlightMoreText(highlight) {
  if (highlight) {
    return "This range is highlighted!";
  }

  return "Nothing highlighted";
}

Supported commenting syntax:

Style	Syntax
C-style	`/* ... */` and `// ...`
JSX-style	`{/* ... */}`
Bash-style	`# ...`
HTML-style	`<!-- ... -->`

We will do our best to infer which set of comment styles to use based on the language, and default to allowing all comment styles. If there's a comment style that is not currently supported, we are open to adding them! Pull requests welcome. Note that different comment styles have no semantic difference, only their content does.

You can set your own background color for highlighted code line in your src/css/custom.css which will better fit to your selected syntax highlighting theme. The color given below works for the default highlighting theme (Palenight), so if you are using another theme, you will have to tweak the color accordingly.

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

/* If you have a different syntax highlighting theme for dark mode. */
[data-theme="dark"] {
  /* Color which works with dark mode syntax highlighting theme */
  --docusaurus-highlighted-code-line-bg: rgb(100, 100, 100);
}

If you also need to style the highlighted code line in some other way, you can target on theme-code-block-highlighted-line CSS class.

用元数据字符串高亮显示

You can also specify highlighted line ranges within the language meta string (leave a space after the language). To highlight multiple lines, separate the line numbers by commas or use the range syntax to select a chunk of lines. This feature uses the parse-number-range library and you can find more syntax on their project details.

```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;

prefer comments

Prefer highlighting with comments where you can. By inlining highlight in the code, you don't have to manually count the lines if your code block becomes long. If you add/remove lines, you also don't have to offset your line ranges.

- ```jsx {3}
+ ```jsx {4}
  function HighlightSomeText(highlight) {
    if (highlight) {
+     console.log('Highlighted text found');
      return 'This text is highlighted!';
    }

    return 'Nothing highlighted';
  }
  ```

Below, we will introduce how the magic comment system can be extended to define custom directives and their functionalities. The magic comments would only be parsed if a highlight metastring is not present.

自定义魔术注释

// highlight-next-line and // highlight-start etc. are called "magic comments", because they will be parsed and removed, and their purposes are to add metadata to the next line, or the section that the pair of start- and end-comments enclose.

You can declare custom magic comments through theme config. For example, you can register another magic comment that adds a code-block-error-line class name:

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

module.exports = {
  themeConfig: {
    prism: {
      magicComments: [
        // Remember to extend the default highlight class name as well!
        {
          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;
}

In JavaScript, trying to access properties on `null` will error.

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

http://localhost:3000

In JavaScript, trying to access properties on null will error.

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

If you use number ranges in metastring (the {1,3-4} syntax), Docusaurus will apply the first magicComments entry's class name. This, by default, is theme-code-block-highlighted-line, but if you change the magicComments config and use a different entry as the first one, the meaning of the metastring range will change as well.

You can disable the default line highlighting comments with magicComments: []. If there's no magic comment config, but Docusaurus encounters a code block containing a metastring range, it will error because there will be no class name to apply—the highlighting class name, after all, is just a magic comment entry.

Every magic comment entry will contain three keys: className (required), line, which applies to the directly next line, or block (containing start and end), which applies to the entire block enclosed by the two comments.

Using CSS to target the class can already do a lot, but you can unlock the full potential of this feature through swizzling.

npm
Yarn
pnpm

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

yarn swizzle @docusaurus/theme-classic CodeBlock/Line

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

The Line component will receive the list of class names, based on which you can conditionally render different markup.

行编号

You can enable line numbering for your code block by using showLineNumbers key within the language meta string (don't forget to add space directly before the key).

```jsx {1,4-6,11} showLineNumbers
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;

交互式代码编辑器

(Powered by React Live)

You can create an interactive coding editor with the @docusaurus/theme-live-codeblock plugin. First, add the plugin to your package.

npm
Yarn
pnpm

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

yarn add @docusaurus/theme-live-codeblock

pnpm add @docusaurus/theme-live-codeblock

You will also need to add the plugin to your docusaurus.config.js.

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

To use the plugin, create a code block with live attached to the language meta string.

```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>It is {date.toLocaleTimeString()}.</h2>
    </div>
  );
}
```

The code block will be rendered as an interactive editor. Changes to the code will reflect on the result panel live.

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>It is {date.toLocaleTimeString()}.</h2>
    </div>
  );
}

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>It is {date.toLocaleTimeString()}.</h2>
    </div>
  );
}

结果

导入

react-live and imports

It is not possible to import components directly from the react-live code editor, you have to define available imports upfront.

By default, all React imports are available. If you need more imports available, swizzle the react-live scope:

npm
Yarn
pnpm

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

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,
    }}
  />
);

// Add react-live imports you need here
const ReactLiveScope = {
  React,
  ...React,
  ButtonExample,
};

export default ReactLiveScope;

The ButtonExample component is now available to use:

http://localhost:3000

实时编辑器

function MyPlayground(props) {
  return (
    <div>
      <ButtonExample onClick={() => alert("hey!")}>Click me</ButtonExample>
    </div>
  );
}

function MyPlayground(props) {
  return (
    <div>
      <ButtonExample onClick={() => alert("hey!")}>Click me</ButtonExample>
    </div>
  );
}

结果

必须呈现 (noInline)

The noInline option should be used to avoid errors when your code spans multiple components or variables.

```jsx live noInline
const project = "Docusaurus";

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

render(<Greeting />);
```

Unlike an ordinary interactive code block, when using noInline React Live won't wrap your code in an inline function to render it.

You will need to explicitly call render() at the end of your code to display the output.

http://localhost:3000

实时编辑器

const project = "Docusaurus";

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

render(
  <Greeting />
);

const project = "Docusaurus";

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

render(
  <Greeting />
);

结果

在代码块中使用 JSX 标记

Code block in Markdown always preserves its content as plain text, meaning you can't do something like:

type EditUrlFunction = (params: {
  // This doesn't turn into a link (for good reason!)
  version: <a href="/docs/versioning">Version</a>;
  versionDocsDirPath: string;
  docPath: string;
  permalink: string;
  locale: string;
}) => string | undefined;

If you want to embed HTML markup such as anchor links or bold type, you can use the <pre> tag, <code> tag, or <CodeBlock> component.

<pre>
  <b>Input: </b>1 2 3 4{"\n"}
  <b>Output: </b>"366300745"{"\n"}
</pre>

http://localhost:3000

Input: 1 2 3 4
Output: "366300745"

MDX is whitespace insensitive

MDX is in line with JSX behavior: line break characters, even when inside <pre>, are turned into spaces. You have to explicitly write the new line character for it to be printed out.

警告

Syntax highlighting only works on plain strings. Docusaurus will not attempt to parse code block content containing JSX children.

多语言支持的代码块

With MDX, you can easily create interactive components within your documentation, for example, to display code in multiple programming languages and switch between them using a tabs component.

Instead of implementing a dedicated component for multi-language support code blocks, we've implemented a general-purpose <Tabs> component in the classic theme so that you can use it for other non-code scenarios as well.

The following example is how you can have multi-language code tabs in your docs. Note that the empty lines above and below each language block are intentional. This is a current limitation of MDX: you have to leave empty lines around Markdown syntax for the MDX parser to know that it's Markdown syntax and not 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:

http://localhost:3000

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 插件

在 npm 和 Yarn 中显示 CLI 命令是非常常见的需求，例如:

npm
Yarn
pnpm

npm install @docusaurus/remark-plugin-npm2yarn

yarn add @docusaurus/remark-plugin-npm2yarn

pnpm 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: {
          remarkPlugins: [[require("@docusaurus/remark-plugin-npm2yarn"), { converters: ["pnpm"] }]],
          // ...
        },
      },
    ],
  ],
};

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

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

配置

Option	类型	默认	描述
`sync`	`boolean`	`false`	Whether to sync the selected converter across all code blocks.
`converters`	`array`	`'yarn'`, `'pnpm'`	The list of converters to use. The order of the converters is important, as the first converter will be used as the default choice.

在 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>Hello, {props.name}</h1>;
}`}
      </CodeBlock>
    </div>
  );
}

http://localhost:3000

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

The props accepted are language, title and showLineNumbers, in the same way as you write Markdown code blocks.

Although discouraged, you can also pass in a metastring prop like metastring='{1-2} title="/src/components/HelloCodeTitle.js" showLineNumbers', which is how Markdown code blocks are handled under the hood. However, we recommend you use comments for highlighting lines.

As previously stated, syntax highlighting is only applied when the children is a simple string.

代码块

代码标题​

语法高亮显示​

主题​

支持的语言​

行高亮显示​

用注释高亮显示​

用元数据字符串高亮显示​

自定义魔术注释​

行编号​

交互式代码编辑器​

导入​

必须呈现 (noInline)​

在代码块中使用 JSX 标记​

多语言支持的代码块​

Docusaurus npm2yarn remark 插件​

配置​

在 JSX 中的用法​

代码标题

语法高亮显示

主题

支持的语言

行高亮显示

用注释高亮显示

用元数据字符串高亮显示

自定义魔术注释

行编号

交互式代码编辑器

导入

必须呈现 (noInline)

在代码块中使用 JSX 标记

多语言支持的代码块

Docusaurus npm2yarn remark 插件

配置

在 JSX 中的用法