Skip to main content

Highlighting Code in Markdown with Rehype Pretty Code

  • Beautiful Markdown Code Highlighting with Rehype Pretty Code

Syntax highlighting is a must-have for any blog that includes code snippets. But it’s not always easy to get right.

My favourite solution is Rehype Pretty Code. It’s a rehype plugin that adds syntax highlighting to markdown code blocks at build time. It works with any static site generator and supports any VSCode theme.

It builds on the excellent shiki library by adding a few extra features:

  • TODO: validate and add the rest
  • It can highlight code blocks in any language, not just the ones supported by shiki.
  • It can highlight inline code snippets.

How to use it

  1. Install the plugin:

    npm install rehype-pretty-code

  2. Add the plugin to your rehype pipeline:

     const rehype = require('rehype')
 const rehypePrettyCode = require('rehype-pretty-code')
 
 rehype()
   .use(rehypePrettyCode)
   .process(/* ... */)

  3. Add a VS Code theme to your site:

    const rehype = require('rehype')
const rehypePrettyCode = require('rehype-pretty-code')
 
rehype()
  .use(rehypePrettyCode, { theme: 'vscode-dark-plus' })
  .process(/* ... */)

  4. Add a fenced code block to your markdown:

    ```js
const fruit = [
  'apple',
  'apple',
  'apple'
  'orange',
  'orange',
  'orange',
  'banana',
  'banana',
  'banana',
]
```

  5. That’s it! The code block will now be syntax highlighted using the theme you chose.

  6. You can also add a title, a caption, highlight lines and/or characters, and show line numbers. See the documentation for more details.

  7. If you want to use a different theme, you can find a list of supported themes here.

  8. If you want to use a custom theme, you can find instructions here.

  9. If you want to use a custom language, you can find instructions here.

  10. If you want to use a custom inline syntax highlighting token, you can find instructions here.

  11. If you want to use a custom inline syntax highlighting token, you can find instructions here.

  12. If you want to use a custom inline syntax highlighting token, you can find instructions here.

Meta strings

Can add strings to the top fence of a code block to add a title, a caption, highlight lines and/or characters, and show line number.

For example, this markdown…

```js title="constants/fruit.js" caption="Delish!" showLineNumbers {2-3,10} /orange/1-2 /banana/1
const fruit = [
  'apple',
  'apple',
  'apple'
  'orange',
  'orange',
  'orange',
  'banana',
  'banana',
  'banana',
]
```

…will output this:

constants/fruit.js
const fruit = [
  'apple',
  'apple',
  'apple'
  'orange',
  'orange',
  'orange',
  'banana',
  'banana',
  'banana',
]
Delish!

Or here’s a diff:

import useSWR from 'swr'
 
function Profile() {
  const { data, error } = useSWR('/api/user', fetcher)
 
-  if (error) return <div>failed to load</div>
+  if (!data) return <div>loading...</div>
  return <div>hello {data.name}!</div>
}

Styling

The styling shown above is all customizable by setting a theme and then adding styles to the following selectors (which are unstyled by default):

  • TODO: add the rest
  • line: [data-line]
  • title: [data-rehype-pretty-code-title]
  • highlighted line: [data-line-highlighted]
  • highlighted characters: [data-highlighted-chars]

Inline syntax highlighting

  • This is what makes this library special
  • Can also create shortcuts for custom inline highlighting tokens (show config setting and an example)

Multiple themes

  • Note: to display markdown code blocks as markdown (instead of parsing them), wrap the code block in a `````markdown` fence with four backticks.

Further reading

Inbox