LITERAT

Fullstack Developer & Whitewater Kayaker & Scout

GatsbyJS - How to setup syntax highligting your in posts

How to setup Gatsby to highlight syntax of code examples in your posts

2. 3. 2022Development Edit on GitHub

Running a developer's blog means that you want to also show a lot of code examples in your posts. And you also want the code to be read as easily as is in your code editor. That means using some kind of syntax highlighting.

If you are a user of VSCode like me, you probably want to highlight your code the same way as is in your editor. It can be done in a very easy way.

Find and install the right theme

Just find your favorite VSCode theme on GitHub and check if there are predefined themes in JSON like in vsc-community-material-theme. If so, just install it to your project.

npm install https://github.com/material-theme/vsc-community-material-theme

// or

yarn add https://github.com/material-theme/vsc-community-material-theme

Then your package.json should look like this:

// package.json
{
  "dependencies": {
    // ...
    "vsc-community-material-theme": "https://github.com/material-theme/vsc-community-material-theme"
    // ...
  }
}

Configure Gatsby

In the next step you must configure your Gatsby site to use this theme. But how?

Since Visual Studio Code is built with web technology and has incredible syntax highlighting capabilities, Andrew Branch decided to make the syntax highlighting of VSCode available for gatsby sites with his library gatsby-remark-vscode.

This allows you to use VSCode extensions like syntax highlighting themes or language definitions and get the same syntax highlighting in your Gatsby site that you would otherwise have in your editor.

That is what I am currently using on this blog. And it has also many amazing features like:

line number toggle, highlighting of specific lines
- ```js {numberLines}
diff highlighting to highlight changes
- ```js {diff} and + and - on lines
highlighting of a specific line of code
- ```js{1,3-5}
switch between dark & light mode, change when specific media queries or parent selectors are matched (e.g. high contrast mode)
highlighting inline code with an inline code marker and then using that code marker by writing something like `js»const answer = 42` to get highlighted inline code like const answer = 42.

To do so you must go to gatsby-config.js and extends the configuration you use with gatsbyRemarkVSCode.remarkPlugin and pass it some options. theme is the most important option and it determines which theme will be used. It matches with the file name in the themes directory of the installed repository. To switch themes just use a different file name.

My current options for gatsby-remark-vscode in gatsby-config.js look like this:

// /gatsby-config.js

const gatsbyRemarkVSCode = require('gatsby-remark-vscode');
// ...
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-plugin-mdx',
      options: {
        remarkPlugins: [
          [
            gatsbyRemarkVSCode.remarkPlugin,
            {
              theme: `Community-Material-Theme-Default-High-Contrast`,
              extensions: ['vsc-community-material-theme'],
              inlineCode: {
                marker: '»',
              },
            },
          ],
        ],
      },
    },
  ],
};

Syntax highlighting in MDX

Syntax highlighting is then applied to the pre HTML tag.

If you are using MDX just like me, you can even modify this pre tag with a custom component. For me it is <Pre /> component with additional styling using styled-components.

// src/components/mdx/index.tsx

export default {
  pre: Pre,
  code: (props) => <Code {...props} />,
  inlineCode: (props) => <InlineCode {...props} />,
};

// src/components/mdx/Pre.tsx

import styled from 'styled-components';

const Pre = styled.pre`
  margin-top: calc(2 * (1.68 * (10px + 0.2vw) + 0.2vw));
  margin-bottom: calc(2 * (1.68 * (10px + 0.2vw) + 0.2vw));
  margin-right: calc(-1 * ((100vw - 100%) / 2));
  margin-left: calc(-1 * ((100vw - 100%) / 2));
  padding: calc(1 * (1.68 * (18px + 0.2vw) + 0.2vw)) 0;
  font-size: 0.85em;
  font-family: 'Fira Code', Menlo, Consolas, Monaco, 'Andale Mono', 'Ubuntu Mono', monospace;

  @media only screen and (min-width: 600px) {
    clip-path: polygon(0 5%, 100% 0, 100% 95%, 0% 100%);
  }
`;

export default Pre;

Display language attribute

If you want to display a language of code in your code block, you can use the data-language attribute to do so.

// src/components/mdx/Pre.tsx

  :after {
    content: attr(data-language);
    opacity: 0.7;
    display: inline-block;
    transform: translate(-16px, 24px);
    text-align: right;
    width: 60%;
    margin-left: 20%;
    margin-right: 20%;
    font-size: 1.5rem;
  }

CSS-in-JS support

Amongst all of this goodness, the feature that I like best is that you can use any VSCode extension that makes changes to the syntax highlighting. To have nice CSS-in-JS syntax highlighting in VSCode, I use an extension called vscode-styled-components.

To set this up you must add that extension to the Gatsby project and then configure gatsby-remark-vscode to use it. You have to install it directly from GitHub because it's not published as an NPM package.

Conclusion

If you run a developer blog like me, it is a good idea to use syntax highlighting in your code blocks. Use libraries that are designed for this use case and make sure that you use them in the right way.