Nextra 中文文档
语法高亮

语法高亮

Nextra 使用 Shiki (opens in a new tab) 在构建时进行语法高亮。它非常可靠且高效。例如,在你的 Markdown 文件中添加这个:

Markdown
```js
console.log('hello, world')
```

效果:

console.log('hello, world')

特性

内嵌代码

内嵌语法高亮如 let x = 1 也是通过 {:} 语法实现的:

Markdown
Inlined syntax highlighting is also supported `let x = 1{:jsx}` via:

高亮行

你可以通过给代码块添加一个 {} 属性来高亮特定的代码行:

Markdown
```js {1,4-5}
import { useState } from 'react'
 
function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}
```

效果:

import { useState } from 'react'
 
function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}

高亮子字符串

你可以通过给代码块添加一个 // 属性来高亮特定的代码 子字符串: 例如下面将高亮 useState

Markdown
```js /useState/
import { useState } from 'react'
 
function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}
```
import { useState } from 'react'
 
function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}

你可以通过在其后添加一个数字来仅高亮该子串的部分出现:/str/1,或者多个:/str/1-3/str/1,3

复制按钮

通过添加一个 copy 属性,在用户悬停在代码块上时会添加一个复制按钮:

Markdown
```js copy
console.log('hello, world')
```

效果:

console.log('hello, world')

你可以通过在你的 Nextra 配置文件 (next.config.js 文件) 中设置 defaultShowCopyCode: true 来全局启用这个功能。 一旦它在全局启用了,你可以通过 copy=false 属性来禁用它。

行号

你可以通过添加一个 showLineNumbers 属性来给你的代码块添加行号:

Markdown
```js showLineNumbers
import { useState } from 'react'
 
function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}
```

效果:

import { useState } from 'react'
 
function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}

文件名和标题

您可以通过添加 filename 属性为您的代码块添加文件名或标题:

Markdown
```js filename="example.js"
console.log('hello, world')
```

效果:

example.js
console.log('hello, world')

ANSI 高亮

您可以突出显示 ANSI 转义码:

Markdown
```ansi
 ✓ src/index.test.ts (1)
   Test Files  1 passed (1)
        Tests  1 passed (1)
     Start at  23:32:41
     Duration  11ms
   PASS  Waiting for file changes...
         press h to show help, press q to quit
```

效果:

  src/index.test.ts (1)
   Test Files  1 passed (1)
        Tests  1 passed (1)
     Start at  23:32:41
     Duration  11ms
   PASS  Waiting for file changes...
         press h to show help, press q to quit

支持的语言

查看此列表 (opens in a new tab) 以获取所有支持的语言。

自定义主题

Nextra 使用 CSS 变量来定义标记的颜色。您可以注入 全局 CSS (opens in a new tab) 以在亮色/暗色主题下进行自定义。例如,这是默认的 标记,您可以覆盖其中的任何一个:

styles.css
:root {
  --shiki-color-text: #414141;
  --shiki-color-background: transparent;
  --shiki-token-constant: #1976d2;
  --shiki-token-string: #22863a;
  --shiki-token-comment: #aaa;
  --shiki-token-keyword: #d32f2f;
  --shiki-token-parameter: #ff9800;
  --shiki-token-function: #6f42c1;
  --shiki-token-string-expression: #22863a;
  --shiki-token-punctuation: #212121;
  --shiki-token-link: #22863a;
}
 
.dark {
  --shiki-color-text: #d1d1d1;
  --shiki-token-constant: #79b8ff;
  --shiki-token-string: #ffab70;
  --shiki-token-comment: #6b737c;
  --shiki-token-keyword: #f97583;
  --shiki-token-parameter: #ff9800;
  --shiki-token-function: #b392f0;
  --shiki-token-string-expression: #4bb74a;
  --shiki-token-punctuation: #bbb;
  --shiki-token-link: #ffab70;
}

使用动态内容

由于语法高亮是在构建时完成的,因此您不能在代码块中使用动态内容。 但是,由于MDX非常强大,因此可以通过客户端JS进行一些变通。例如:

dynamic_code.js
function hello () {
  const x = 2 + 3
  console.log(1)
}
Increase the numberChange to `1 + 1`

这种变通方法有一个局限性,即更新的内容不会重新进行高亮显示。例如,如果我们将数字更新为 1 + 1,它将被错误地高亮显示。

查看 code (opens in a new tab) 以了解其工作原理。

禁用语法高亮

您可以选择不使用内置的语法高亮显示功能,而使用自己的方式。 您可以在 Nextra 配置 (next.config.js 文件) 中设置 codeHighlight: false 来全局禁用语法高亮显示。

OptionTypeDescription
codeHighlightboolean启用或禁用语法突出显示。默认值为“true”

自定义语法

Shiki接受 VSCode TextMate Grammar (opens in a new tab) 来进行自定义语言语法的语法高亮。

您可以通过在next.config.js中Nextra配置的mdxOptions.rehypePrettyCodeOptions选项中覆盖getHighlighter函数来提供这些语法:

next.config.js
import { BUNDLED_LANGUAGES } from 'shiki'
 
nextra({
  // ... other options
  mdxOptions: {
    rehypePrettyCodeOptions: {
      getHighlighter: options =>
        getHighlighter({
          ...options,
          langs: [
            ...BUNDLED_LANGUAGES,
            // custom grammar options, see the Shiki documentation for how to provide these options
            {
              id: 'my-lang',
              scopeName: 'source.my-lang',
              aliases: ['mylang'], // Along with id, aliases will be included in the allowed names you can use when writing markdown.
              path: '../../public/syntax/grammar.tmLanguage.json'
            }
          ]
        })
    }
  }
})

自定义主题

mdxOptions.rehypePrettyCodeOptions 中,你也可以提供自定义主题,而不是依赖 CSS 变量

next.config.js
nextra({
  // ... other options
  mdxOptions: {
    rehypePrettyCodeOptions: {
      // VSCode theme or built-in Shiki theme, see Shiki documentation for more information
      theme: JSON.parse(
        readFileSync('./public/syntax/arctis_light.json', 'utf8')
      )
    }
  }
})

多主题

Nextra目前不支持指定多个主题。因为Shiki为每个主题渲染多个代码块,并用属性data-theme标记它们,例如data-theme="dark"

然而,将来将支持多个主题。你可以在shikiji(Shiki的新分支) https://github.com/antfu/shikiji#multiple-themes (opens in a new tab) 中跟踪进展,该分支已经支持多个主题而无需渲染多个代码块。