How I Handle Syntax Highlighting

For my first post of 2025, I'll go over how I handle syntax highlighting on my blog. Or in other words, how to make highlight.js, MDX, and Next.js's App Router play together nicely.

A Little Background

The idea for my blog is to have it be statically generated, since most of the content is itself static.

Having pre-built pages generally makes the entire experience faster, and going along with this idea, I also leverage React Server Components using Next's App Router. These components require very little work on the client: they render exclusively on the server, are not included in the JS bundle, never hydrate, and never re-render. I always refer to Josh Comeau's Making Sense of React Server Components when I need a refresher on RSCs.

I also use MDX to write my blog posts. This allows me to use markdown in combination with React components in the same file, and therefore in the same page!

The Problem

Sounds great right? But the problem is that MDX does not support syntax highlighting. I wanted a simple way to apply syntax highlighting to the code blocks in my articles, while avoiding any extra work on the client.

I've used highlight.js in the past and have been extremely satisfied with its performance and DX, so I set out to integrate it once more in my application. All I want to do is specify a code block using the triple backtick notation in my .mdx file, then MDX and highlight.js should take care of it from there.

A Solution

Let's take a look at a possible solution together.

In the end, it's fairly simple. We'll simply be using the highlights.js highlight() method to output the required html in the useMDXComponents() hook. However, there are some small implementation details that are kind of tricky.

The highlight() Method

The highlight() method takes your code as a string and returns an html string with highlighting markup.

We'll need to pass two arguments to highlight(): the code, and the language it's written in.

import hljs from "highlight.js"

const html = hljs.highlight('const greeting = "Hello, World!"', {
  language: "ts",
}).value

console.log(html)

The output html will be:

<span class="hljs-keyword">const</span> greeting = <span class="hljs-string">&quot;Hello, World!&quot;</span>

Notice the CSS classes highlight.js uses to apply syntax highlighting: hljs-keyword, hljs-string... For this to work, you'll need to include a highlight.js stylesheet. There are plenty of themes to choose from on the highlight.js GitHub repo.

Configuring the useMDXComponents() Hook

The Next.js documentation has a great page on configuring MDX.

As stated in the docs, to use MDX with the Next App Router, we need an mdx-components.tsx file. This is where we have our useMDXComponents() hook. Remember, at its core MDX takes your markdown file and transforms it into html. This hook basically lets you tell MDX how to process the different html tags it comes across for any given file.

When MDX comes across the markdown for a code block, it'll render a <pre> html tag wrapping a <code> tag. It's at this point that we'll want to call thehighlight() method:

export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {
    // TODO: call highlight() method here
    pre: (props) => <pre {...props} />,
    ...components,
  }
}

Given a const greeting = "Hello, World!" code block, if we inspect the props object we'll see something that looks like this:

{
  children: {
    '$$typeof': Symbol(react.transitional.element),
    type: 'code',
    key: null,
    props: {
      className: 'language-ts',
      children: 'const greeting = "Hello, World!"\n'
    },
    _owner: {
      name: '_createMdxContent',
      env: 'Server',
      key: null,
      owner: [Object],
      props: [Object]
    },
    _store: {}
  }
}

As you can see we want to access props.children.props.className to get the language and props.children.props.children to get the code itself.

props.children.props.className is a string that looks like language-<language>. Where <language> is the language specified in the markdown for the code block. We'll want to split() the string to get the language without the prepended language-, and pass it to the highlight() method. The full language-<language> string is still needed because it's a higlight.js class name used to apply the CSS necessary for syntax highlighting.

Props Type Problem

Unfortunately, the type of props is not accurate enough for our needs:

DetailedHTMLProps<HTMLAttributes<HTMLPreElement>, HTMLPreElement>

We're missing the prop.children.props.className and prop.children.props.children properties.

Additionally, there could be other instances where MDX needs to render a <pre> tag, and we don't want to apply syntax highlighting in those cases.

This is an apt situation to use a library like zod to: define a schema for our props object, assert we're getting a code block, and act accordingly.

Given the props we expect to receive in case of a code block, we can define the following schema:

import { z } from "zod"

export const codeBlockPropsSchema = z.object({
  children: z.object({
    type: z.literal("code"),
    props: z.object({
      className: z.string().startsWith("language-"),
      children: z.string(),
    }),
  }),
})

Putting it all Together

Now we're ready to put everything together. We'll return a <pre> tag wrapping a <code> tag where we'll need to use the dangerouslySetInnerHTML prop to correctly render the html outputted by the highlight() method.

Another detail is that highlight() can throw an error, if it does we abandon syntax highlighting and just return the original <pre> tag

Here's the resulting mdx-components.tsx file:

import { codeBlockPropsSchema } from "@/schemas"
import hljs from "highlight.js"
import type { MDXComponents } from "mdx/types"

export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {
    pre: (props) => {
      const result = codeBlockPropsSchema.safeParse(props)

      if (result.error) {
        return <pre {...props} />
      }

      const { className, children: code } = result.data.children.props
      const language = className.split("-")[1]

      let html = undefined
      try {
        html = hljs.highlight(code, {
          language: language,
        }).value
      } catch {
        return <pre {...props} />
      }

      return (
        <pre>
          <code
            className={`${className} hljs`}
            dangerouslySetInnerHTML={{
              __html: html,
            }}
          ></code>
        </pre>
      )
    },
    ...components,
  }
}

Notice the extra hjls class I added, that class is not included in the html outputted by highlight(), but it is needed to set the text color for a given highlight.js theme. Now, remember to include a highlight.js stylesheet in your application and you're good to go!

Conclusion

In my post on implementing dark mode I talked about how to toggle stylesheets based on the current theme, if you're interested, see Dark Mode, a Not so Simple Story.

I have to say I'm really happy with the result here. All the work gets done on the client and the resulting code blocks look great! However, I think my current implementation can be improved. It was the easiest solution to integrate with the knowledge I had at the time I was creating this blog, but I know there's more out there.
In these cases I need to remind myself what the purpose of my blog is. And that's the content. I don't want to spend too much time implementing the perfect syntax highlighting system, supporting features that don't add much to my WHY.
That being said, I'm still curious about exploring plugins like rehype-pretty-code which offer cool features like line numbers, line highlighting, inline code highlighting, and more!