Home

MDX Syntax Highlighting in Next.js using Highlight.js

MDX Syntax Highlighting

In this tutorial, we'll setup highlight.js using the rehypeHighlight MDX plugin to allow code blocks in our mdx files to include syntax highlighting. We'll then choose a highlight.js theme to add to our Next.js site in order to style the code blocks as we choose.

Requirements

For this tutorial, I expect you've got MDX setup within your Next.js application. If you don't already then take a look here to setup a mdx blog using Next.js. I'll be using the next-mdx-remote MDX provider however this tutorial will work for other providers such as @next/mdx too.

With our application setup, we need to install the rehype-highlight plugin, which will add CSS classes to different parts of our code snippets (allowing our chosen highlight.js style to stylise the different parts of the code). To install the plugin, run this command:

npm install rehype-highlight

Setup Highlight.js Plugin

With the plugin installed, we now need to add it to our MDX provider. To do this, first import the plugin into your "blog" page and add it to the array of "rehypePlugins":

// app/blog/[slug]/page.tsx
import rehypeHighlight from 'rehype-highlight';

const options = {
    mdxOptions: {
        remarkPlugins: [],
        rehypePlugins: [rehypeHighlight],
    }
}

Then we pass these options through to our MDXRemote component:

// app/blog/[slug]/page.tsx
<MDXRemote source={props.content} components={{Button}} options={options}/>

Additional Configuration

The rehypeHighlight package does allow additional configuration which you can see here, one of those options is enabling additional languages which you can do by changing your mdx options to something like this:

// app/blog/[slug]/page.tsx
import rehypeHighlight from 'rehype-highlight';

import langHttp from 'highlight.js/lib/languages/http'
import langNginx from 'highlight.js/lib/languages/nginx'

const options = {
    mdxOptions: {
        remarkPlugins: [],
        rehypePlugins: [
            [ rehypeHighlight, { languages: { http: langHttp, nginx: langNginx} }]
        ],
    }
}

Here you can see we are adding the rehypeHighlight plugin while also configuring 2 additional languages (http and nginx). The list of all supported languages can be found here.

Styling your Code

Now that we have the plugin setup, our code blocks now have the correct CSS class names ready to be styled. The next step is to choose the theme we would like to use.

  1. Find the theme you want to use: Highlight.js Styles - Demo
  2. Download the theme from Github: Highlight.js Styles - Download
  3. Place the downloaded CSS file in the following new directory in your project: styles/highlight-js

Highlight.js Styles

We can now import this style into our blog page so it'll automatically be pulled in by the browser whenever someone enters a page with code blocks:

// app/blog/[slug]/page.tsx
import "@/styles/highlight-js/github-dark.css"

Fixing Styles for TailwindCSS

If you're using TailwindCSS, then there is 1 small fix you can make to the .css file you download. Find the .hljs tag in the file and update it to include pre:has(.hljs), too:

Turn the following code:

.hljs {
    color: #c9d1d9;
    background: #0d1117;
}

Into this:

pre:has(.hljs), .hljs {
    color: #c9d1d9;
    background: #0d1117;
}

This selector will add the background colour not only to the highlight.js element (.hljs) but also to any pre tags that contain child elements with .hljs. This ensures that the full background colour of our codeblock is consistent.

Using Syntax Highlighting in MDX

To add syntax highlighting to your MDX pages, you need to add the language to your code blocks, like this:

```python
print("Hello, World!")
```

By adding the "python" language to our codeblock, the block will now be styled with syntax highlighting:

print("Hello, World!")

That's it, you've now got code syntax highlighting setup in your MDX Next.js site. By default rehypeHighlight supports 35 default supported languages however you can easily register more languages.

Thanks for reading this tutorial, if you learnt anything from it (or have any questions), feel free to reach out on Twitter.

If you liked this tutorial, then I have many more just like it to help you learn more about MDX & Next.js: