How to set up syntax highlighting for Gatsby

Using gatsby-remark-vscode

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. It’s what is currently used on this blog and has has many amazing features:

• Line number toggle, highlighting of specific lines
• Diff highlighting to highlight changes
• 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 to get highlighted inline code like ​const answer = 42.

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

To set this up on this site I added that extension to my Gatsby project and then configured gatsby-remark-vscode to use it. I had to install it directly from GitHub because it’s not published as an NPM package. I’ve also added slack-theme for both light and dark mode themes using the same mechanism and configured them accordingly.

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

theme: {
  default: 'Slack Theme Ochin',
  parentSelector: {
    'html[data-mode=dark]': 'Slack Theme Dark Mode',
  },
},
inlineCode: {
  marker: '»',
},
extensions: ['slack-theme', 'vscode-styled-components']

With this configuration and a little extra styling, the source code from the screenshot in the chapter above looks like this:

/** @jsx jsx */
import { css, jsx } from '@emotion/core';
import { BREAKS } from '../settings';

export const Button = ({ ...props }) => (
  <button
    css={css`
      background: var(--color-primary-light);
      [data-mode='dark'] & {
        background: var(--color-primary-dark);
      }
      padding: 2px 4px;
      @media (min-width: ${BREAKS.TABLET_PORTRAIT}px) {
        padding: 4px 9px;
      }
    `}
    {...props}
  />
);

As you can see, this is much more consistent and readable.

Using shiki and twoslash

Another syntax highlighting library that I’ve contributed to in the past is called Shiki. It works with VSCode themes and languages and is used in both the VSCode website as well as the TypeScript website.

You can use Shiki in your Gatsby site by using gatsby-remark-shiki. However, gatsby-remark-vscode described above has more features as of today and is nicely maintained, so it is my preferred choice.

If you take a look at specific parts of the TypeScript website, you will see that their code snippets not only have nice syntax highlighting, but also have TypeScript type annotation tooltips and TypeScript error checking. This functionality is provided by a library called twoslash.

If you’re going to have a lot of TypeScript code snippets, you can use gatsby-remark-shiki-twoslash. This package combines Shiki with Twoslash and is used in the TypeScript website.