跳转至主内容
Version: 2.0.0-beta.1 🚧

代码块

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

代码标题#

您可以在语言后添加 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('每个仓库都应该有个吉祥物。');

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

举个例子,如果您喜欢 dracula 高亮主题:

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

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

注意

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

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

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

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

如果您想添加 Prism 所不支持语言的语法高亮功能,您可变换(Swizzle) prism-include-languages

npm 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);}

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

您也可以使用 highlight-next-linehighlight-starthighlight-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 install --save @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 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>

渲染效果如下:

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

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

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