rehype-shiki

Highlight code blocks in html with shiki.

How to install

yarn add shiki @stefanprobst/rehype-shiki

How to use

This package is a rehype plugin.

To highlight code blocks in html, specify the code block language via data-language attribute on the <code> element:

import withShiki from '@stefanprobst/rehype-shiki'
import fromHtml from 'rehype-parse'
import toHtml from 'rehype-stringify'
import * as shiki from 'shiki'
import { unified } from 'unified'

const doc = '<pre><code data-language="js">const hello = "World";</code></pre>'

async function createProcessor(options = {}) {
  const highlighter = await shiki.getHighlighter({ theme: 'poimandres' })

  const processor = unified()
    .use(fromHtml)
    .use(withShiki, { highlighter, ...options })
    .use(toHtml)

  return processor
}

createProcessor()
  .then((processor) => processor.process(doc))
  .then((vfile) => {
    console.log(String(vfile))
  })

When used in a unified pipeline coming from Markdown, specify the code block language via code block meta:

import withShiki from '@stefanprobst/rehype-shiki'
import toHtml from 'rehype-stringify'
import fromMarkdown from 'remark-parse'
import toHast from 'remark-rehype'
import * as shiki from 'shiki'
import { unified } from 'unified'

const doc = "```js\nconst hello = 'World';\n```\n"

async function createProcessor(options = {}) {
  const highlighter = await shiki.getHighlighter({ theme: 'poimandres' })

  const processor = unified()
    .use(fromMarkdown)
    .use(toHast)
    .use(withShiki, { highlighter, ...options })
    .use(toHtml)

  return processor
}

createProcessor()
  .then((processor) => processor.process(doc))
  .then((vfile) => {
    console.log(String(vfile))
  })

Configuration

This plugin accepts a preconfigured highlighter instance created with shiki.getHighlighter.

Theme

You can either pass one of the built-in themes as string, or load a custom theme (any TextMate/VS Code theme should work):

// const gloom = await shiki.loadTheme(path.join(process.cwd(), 'gloom.json'))
// const gloom = require('./gloom.json')
const gloom = JSON.parse(
  fs.readFileSync(path.join(process.cwd(), 'gloom.json'), 'utf-8'),
)

const highlighter = await shiki.getHighlighter({ theme: gloom })

const processor = unified()
  .use(fromHtml)
  .use(withShiki, { highlighter })
  .use(toHtml)

Supported languages

Languages which are not included in Shiki's built-in grammars can be added as TextMate grammars:

const sparql = {
  id: 'sparql',
  scopeName: 'source.sparql',
  // provide either `path` or `grammar`
  path: path.join(process.cwd(), 'sparql.tmLanguage.json'),
  // grammar: JSON.parse(
  //   fs.readFileSync(path.join(process.cwd(), "sparql.tmLanguage.json")),
  // ),
}

const highlighter = await shiki.getHighlighter({
  langs: [...shiki.BUNDLED_LANGUAGES, sparql],
})

const processor = unified()
  .use(fromHtml)
  .use(withShiki, { highlighter })
  .use(toHtml)

Note that langs will substitute the default languages. To keep the built-in grammars, concat shiki.BUNDLED_LANGUAGES.

Unknown languages

Unknown languages are ignored by default. You can set ignoreUnknownLanguage: false to throw an error when an unsupported language is encountered.

Highlight lines

It is possible to add additional classes to specific lines. By default, a highlighted class will be added for line ranges defined like this:

<pre><code data-language="js" data-highlight="2..3"
>function hi() {
  console.log('Hi!')
  return true
}</code></pre>

or

```js {highlight: '2..3'}
function hi() {
  console.log('Hi!')
  return true
}
```

You can adjust this by providing a custom getLineOptions function:

processor.use(withShiki, {
  highlighter,
  getLineOptions(node) {
    /** Access any data attributes via `node.properties`, and markdown code block metadata via `node.data.meta`. */
    return [{ line: 2: classes: ['highlighted']}]
  }
})