docs / Configuration / Syntax Highlighting

Syntax Highlighting

1 minute read

Syntax Highlighting

The syntax highlighting uses rehype-pretty-code (which uses shikijs), and is confgured in src/theme/prettyCodeOptions.js. This plugin can use any vscode theme JSON file, or a shiki theme string.

The theme is set up with github-light for the default color theme and a modified version of ayu-mirage for the dark theme.

Overriding the theme

To use your own syntax highlighting theme, you need to:

add the rehype-pretty-code plugin to rehypePlugins in the gatsby-plugin-mdx options
add that plugin to your gatsby-config.js's remarkPlugins

// gatsby-config.js
const rehypePrettyCode = require("rehype-pretty-code");
 
// import the theme's existing remark plugins
const gatsbyRemarkPlugins = require("gatsby-theme-golden-condor/gatsbyRemarkPlugins");
 
// optionally import the theme's existing rehype-pretty-code options
const prettyCodeOptions = require("gatsby-theme-golden-condor/src/theme/prettyCodeOptions");
 
  // ...
  {
    resolve: `gatsby-plugin-mdx`,
    options: {
      gatsbyRemarkPlugins,
      rehypePlugins: [
        [
          rehypePrettyCode,
          {
            // optionally spread the existing options.
            ...prettyCodeOptions,
            // parse your VS Code theme JSON file or a shiki theme string
            theme: JSON.parse(
              fs.readFileSync(
                require.resolve("./src/theme/ayu-mirage.json"),
                "utf-8"
              )
            ),
          },
        ],
      ],
    },
  };

// gatsby-config.js
const rehypePrettyCode = require("rehype-pretty-code");
 
// import the theme's existing remark plugins
const gatsbyRemarkPlugins = require("gatsby-theme-golden-condor/gatsbyRemarkPlugins");
 
// optionally import the theme's existing rehype-pretty-code options
const prettyCodeOptions = require("gatsby-theme-golden-condor/src/theme/prettyCodeOptions");
 
  // ...
  {
    resolve: `gatsby-plugin-mdx`,
    options: {
      gatsbyRemarkPlugins,
      rehypePlugins: [
        [
          rehypePrettyCode,
          {
            // optionally spread the existing options.
            ...prettyCodeOptions,
            // parse your VS Code theme JSON file or a shiki theme string
            theme: JSON.parse(
              fs.readFileSync(
                require.resolve("./src/theme/ayu-mirage.json"),
                "utf-8"
              )
            ),
          },
        ],
      ],
    },
  };

Different theme for dark/light mode

instead of passing the theme directly to the theme key, create separate keys for each theme. These will both be rendered on the page, as <code data-theme="light" /><code data-theme="light" /> and <code data-theme="light" /><code data-theme="light" />.

The theme hides the opposite color mode's syntax highlighting theme with css, in the PrettyCode component and theme.styles.pre.code for code blocks.

{
  // parse your VS Code theme JSON file or a shiki theme string
  theme: {
    dark: JSON.parse(
      fs.readFileSync(
        require.resolve("./src/theme/ayu-mirage.json"),
        "utf-8"
      )
    ),
    light: 'github-light'
  }
},

{
  // parse your VS Code theme JSON file or a shiki theme string
  theme: {
    dark: JSON.parse(
      fs.readFileSync(
        require.resolve("./src/theme/ayu-mirage.json"),
        "utf-8"
      )
    ),
    light: 'github-light'
  }
},

You can see a list of ready to use themes here.

You most likely have to run gatsby clean and rebuild in order for changes to take effect.

rehype-pretty-code API

Code blocks are configured via the meta string after the top codeblock fence.

The below was extracted from the rehype-pretty-code docs, and may be out of date.

See the full docs here: https://github.com/atomiks/rehype-pretty-code

Titles

Add a file title to your code block, with text inside double quotes (""):

```js title="file.js"

```

Line highlighting

Highlight lines 3, and 11 through 14.

```jsx {3, 11-14}
<your code \>
```

import React from "react";
import PropTypes from "prop-types";
import { GatsbyImage } from "gatsby-plugin-image";
import { Card } from "theme-ui";
import { Link } from "gatsby";
 
function PostCard({ post }) {
  return (
    <Card as={Link} variant="post">
      {post.frontmatter.image && (
        <GatsbyImage
          image={post.frontmatter.image.childImageSharp.gatsbyImageData}
          alt={post.frontmatter.title}
        />
      )}
    </Card>
  );
}
 
export default PostCard;

import React from "react";
import PropTypes from "prop-types";
import { GatsbyImage } from "gatsby-plugin-image";
import { Card } from "theme-ui";
import { Link } from "gatsby";
 
function PostCard({ post }) {
  return (
    <Card as={Link} variant="post">
      {post.frontmatter.image && (
        <GatsbyImage
          image={post.frontmatter.image.childImageSharp.gatsbyImageData}
          alt={post.frontmatter.title}
        />
      )}
    </Card>
  );
}
 
export default PostCard;

Word highlighting

Highlight the literal word carrot. Regex is not currently supported.

```js /carrot/

const carrot = "orange";

const carrot = "orange";

Limit word highlighting to specific instances

If you want to limit which words get highlighted, this is possible. For instance:

```js /carrot/1-2,4

The numeric range must be directly after the /.

This will only highlight the first, second, and fourth instances of carrot, but not the third, or fifth+.

Inline highlighting

The default `...` inline code blocks are styled by the theme definition - theme.styles.inlineCode.

To get language specific highlighting like fenced code blocks, append {:lang} (e.g. {:js}) at the end of the inline code to highlight it like it's a regular code block.

`function inline(code) { /* with syntax highlighting */ }{:js}`

Becomes: function inline(code) { /* with syntax highlighting */ }function inline(code) { /* with syntax highlighting */ }

Syntax Highlighting