DocumentationGuideSyntax Highlighting

Syntax Highlighting

Nextra uses Shiki to do syntax highlighting at build time. It’s very reliable and performant. For example, adding this in your Markdown file:

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

Results in:

console.log('hello, world')

Features

Inlined Code

Inlined syntax highlighting like let x = 1 is also supported via the {:} syntax:

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

Highlighting Lines

You can highlight specific lines of code by adding a {} attribute to the code block:

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

Result:

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

Highlighting Substrings

You can highlight specific substrings of code by adding a // attribute to the code block:

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>
}

You can highlight only a part of the occurrences of that substring by adding a number it: /str/1, or multiple: /str/1-3, /str/1,3.

Copy Button

By adding a copy attribute, a copy button will be added to the code block when the user hovers over it:

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

Renders:

console.log('hello, world')

You can enable this feature globally by setting defaultShowCopyCode: true in your Nextra configuration (next.config.mjs file). Once it’s enabled globally, you can disable it via the copy=false attribute.

Line Numbers

You can add line numbers to your code blocks by adding a showLineNumbers attribute:

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

Renders:

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

Filenames and Titles

You can add a filename or a title to your code blocks by adding a filename attribute:

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

Renders:

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

ANSI Highlighting

You can highlight ANSI escape codes:

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

Renders:

 ✓ 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

Supported Languages

Check this list for all supported languages.

With Dynamic Content

Since syntax highlighting is done at build time, you can’t use dynamic content in your code blocks. However, since MDX is very powerful there is a workaround via client JS. For example:

dynamic-code.js
function hello() {
  const x = 2 + 3
  console.log(1)
}

This workaround has a limitation that updated content won’t be re-highlighted. For example if we update the number to 1 + 1, it will be incorrectly highlighted.

Check out the code to see how it works.

Disable Syntax Highlighting

You can opt out of syntax highlighting for using one of your own. You can disable syntax highlighting globally by setting codeHighlight: false in your Nextra configuration (next.config.mjs file).

OptionTypeDescription
codeHighlightbooleanEnable or disable syntax highlighting. Defaults to `true`.

Custom Grammar

Shiki accepts a VSCode TextMate Grammar for syntax highlighting with custom language grammars.

You can provide these grammars by overriding the getHighlighter function in mdxOptions.rehypePrettyCodeOptions option in your Nextra config inside next.config.mjs:

next.config.mjs
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'
            }
          ]
        })
    }
  }
})

Custom Themes

Within mdxOptions.rehypePrettyCodeOptions you may also provide custom themes instead of relying on CSS Variables:

next.config.mjs
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')
      )
    }
  }
})

Multiple Themes (Dark and Light Mode)

Pass your themes to theme, where the keys represent the color mode:

next.config.mjs
nextra({
  // ...
  mdxOptions: {
    rehypePrettyCodeOptions: {
      theme: {
        dark: 'nord',
        light: 'min-light'
      }
    }
  }
})
MarkdownNext.js Link