Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/shuding/nextra/llms.txt

Use this file to discover all available pages before exploring further.

Nextra uses Shiki to apply syntax highlighting at build time, producing beautifully colored code blocks with zero runtime overhead. Because highlighting happens during the build step, your pages load fast and there is no flash of unstyled code. Simply add a fenced code block with a language tag and Nextra handles the rest.

​
Basic Usage

Add a language identifier after the opening triple backticks: 
```js
console.log('hello, world')
```
Renders with full JavaScript syntax coloring. Shiki supports an extensive list of languages — see the complete language list.

​
Features

​
Inline Code Highlighting

Highlight inline code snippets with a language using the {:language} suffix: 
Inline syntax highlighting like `let x = 1{:jsx}` is also supported.
The {:jsx} suffix tells Shiki which grammar to apply to that specific inline token.

​
Line Highlighting

Highlight specific lines by adding a {} attribute with line numbers or ranges: 
```js {1,4-5}
import { useState } from 'react'

function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}
```
This highlights line 1 and lines 4–5. Ranges (4-5) and individual lines (1,3) can be combined freely.

​
Word / Substring Highlighting

Highlight every occurrence of a substring using the /word/ attribute: 
```js /useState/
import { useState } from 'react'

function Counter() {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}
```
To highlight only specific occurrences, append a number or range: /str/1, /str/1-3, or /str/1,3.

​
Copy Button

Add a copy attribute to display a copy-to-clipboard button when the user hovers over the block: 
```js copy
console.log('hello, world')
```
You can enable the copy button globally for every code block by setting defaultShowCopyCode: true in your Nextra configuration in next.config.mjs. Once enabled globally, disable it on individual blocks with copy=false.

​
Line Numbers

Add the showLineNumbers attribute to display a gutter with line numbers: 
```js showLineNumbers
import { useState } from 'react'

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

​
Filenames and Titles

Label a code block with a filename or title using the filename attribute: 
```js filename="example.js"
console.log('hello, world')
```
A tab-style title bar appears above the block with the provided filename.

​
Focus Mode

Use // [!code focus] on specific lines to dim all other lines and draw attention to the focused code: 
```js
function hello() { 
  console.log('focused line')
}
```

​
Diff Annotations

Mark lines as added or removed using // [!code ++] and // [!code --]: 
```js
function greet() {
  console.log('hello') 
  console.log('hello, world') 
}
```
The lines receive green (added) and red (removed) highlighting, clearly communicating what changed.

​
ANSI Highlighting

Use the ansi language tag to highlight terminal output with ANSI escape codes: 
```ansi
[0;32m✓[0m src/index.test.ts
```

​
Custom Grammar

Shiki accepts VSCode TextMate Grammars for custom languages. Override getHighlighter inside mdxOptions.rehypePrettyCodeOptions in your Nextra config: 
import { BUNDLED_LANGUAGES } from 'shiki'

nextra({
  mdxOptions: {
    rehypePrettyCodeOptions: {
      getHighlighter: options =>
        getHighlighter({
          ...options,
          langs: [
            ...BUNDLED_LANGUAGES,
            {
              id: 'my-lang',
              scopeName: 'source.my-lang',
              aliases: ['mylang'],
              path: '../../public/syntax/grammar.tmLanguage.json'
            }
          ]
        })
    }
  }
})

​
Custom Themes

Pass a custom theme or a VSCode theme JSON file via rehypePrettyCodeOptions: 
nextra({
  mdxOptions: {
    rehypePrettyCodeOptions: {
      theme: JSON.parse(
        readFileSync('./public/syntax/my-theme.json', 'utf8')
      )
    }
  }
})
When using the dual-theme object, Nextra switches between themes automatically based on the user’s selected color mode.

​
npm2yarn — Package Manager Tabs

Nextra ships the @theguild/remark-npm2yarn remark plugin. Add the npm2yarn metadata flag to any sh code block and Nextra will automatically render it as a tabbed component showing the equivalent npm, yarn, and pnpm commands: 
```sh npm2yarn
npm i -D pagefind
```
The selected tab is persisted in localStorage so users only have to choose their package manager once across the whole site.

​
Disabling Syntax Highlighting

To opt out of Shiki entirely and use your own highlighting library, set codeHighlight: false in your Nextra config: 
import nextra from 'nextra'

const withNextra = nextra({
  codeHighlight: false
})

export default withNextra({})
OptionTypeDefaultDescription
codeHighlightbooleantrueEnable or disable Shiki syntax highlighting.
defaultShowCopyCodeboolean—Show the copy button on all code blocks by default (disable with copy=false).
mdxOptions.rehypePrettyCodeOptionsobject{}Options forwarded to rehype-pretty-code for custom themes and grammars.

​
TwoSlash (TypeScript Interactive Docs)

Nextra supports TwoSlash for TypeScript code blocks, enabling inline type information and compiler diagnostics directly in your docs. Configure it via rehypePrettyCodeOptions in next.config.mjs following the Shiki TwoSlash documentation.

​
Dynamic Content

Because highlighting runs at build time, code block content must be static. For dynamic code previews, use a client-side component that wraps a pre-highlighted block — see the Nextra dynamic code example for a reference implementation.
Updated content inside a dynamic code block won’t be re-highlighted. For example, replacing 2 + 3 with 1 + 1 at runtime will not update the token colors.

Build docs developers (and LLMs) love

Get started for freeTalk to us