gatsby-remark-prismjs

Adds syntax highlighting to code blocks in markdown files using PrismJS.

Install

npm install --save gatsby-remark-prismjs

How to use

// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-transformer-remark`,
    options: {
      plugins: [
        `gatsby-remark-prismjs`,
      ]
    }
  }
]

Include CSS

Required: Pick a PrismJS theme or create your own

PrismJS ships with a number of themes (previewable on the PrismJS website) that you can easily include in your Gatsby site, or you can build your own by copying and modifying an example (which is what we've done for gatsbyjs.org).

To load a theme, just require its CSS file in your layouts/index.js file, e.g.

// layouts/index.js
require('prismjs/themes/prism-solarizedlight.css')

Optional: Add line highlighting styles

If you want to highlight lines of code, you also need to add some additional CSS that targets our custom line highlighting implementation (which slightly differs from PrismJS's own plugin for that – more on that later).

For simple line highlights similar to PrismJS's, try:

.gatsby-highlight-code-line {
  background-color: #feb;
  display: block;
  margin-right: -1em;
  margin-left: -1em;
  padding-right: 1em;
  padding-left: 0.75em;
  border-left: 0.25em solid #f99;
}

This should work out quite nicely for the "Solarized Light" PrismJS theme we just added in the previous part. However, you will notice that when a highlighted line runs wider than the surrounding code block container (causing a horizontal scrollbar), its background won't be drawn for the initially hidden, overflowing part. :(

We saw others fix that problem and decided to do so, too. Just add the following CSS along your PrismJS theme and the styles for .gatsby-highlight-code-line:

/**
 * Add back the container background-color, border-radius, padding, margin
 * and overflow that we removed from <pre>.
 */
.gatsby-highlight {
  background-color: #fdf6e3;
  border-radius: 0.3em;
  margin: .5em 0;
  padding: 1em;
  overflow: auto;
}

/**
 * Remove the default PrismJS theme background-color, border-radius, margin,
 * padding and overflow.
 * 1. Make the element just wide enough to fit its content.
 * 2. Always fill the visible space in .gatsby-highlight.
 */
.gatsby-highlight pre[class*="language-"] {
  background-color: transparent;
  margin: 0;
  padding: 0;
  overflow: initial;
  float: left; /* 1 */
  min-width: 100%; /* 2 */
}

Usage in Markdown

This is some beautiful code:

```javascript
// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-transformer-remark`,
    options: {
      plugins: [
        `gatsby-remark-prismjs`,
      ]
    }
  }
]
```

You can also add line highlighting. It adds a span around lines of
code with a special class `.gatsby-highlight-code-line` that you can
target with styles. See this readme for more info.

In the following code snippit, lines 1 and 4 through 6 will get
the line highlighting. The line range parsing is done with
https://www.npmjs.com/package/parse-numeric-range.

```javascript{1,4-6}
// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-transformer-remark`,
    options: {
      plugins: [
        `gatsby-remark-prismjs`,
      ]
    }
  }
]
```

Implementation notes

Line highlighting

Please note that we do not use PrismJS's line highlighting plugin. Here's why:

• PrismJS plugins assume you're running things client side, but we are build-time folks.
• PrismJS's line highlighting plugin implementation does not allow for solid background colors or 100% wide backgrounds that are drawn beyond the visible part of the container when content is overflowing.

Our approach follows the Pygments-based implementation of the React Tutorial/Documentation for line highlights:

• It uses a wrapper element <div class="gatsby-highlight"> around the PrismJS-formatted <pre><code>-blocks.`.
• Highlighted lines are wrapped in <span class="gatsby-highlight-code-line">.
• We insert a linebreak before the closing tag of .gatsby-highlight-code-line so it ends up at the start of the follwing line.

With all of this in place, we can apply float:left; min-width:100% to <pre>, throw our overflow and background on .gatsby-highlight, and use display:block on .gatsby-highlight-code-line – all of this coming together to facilitate the desired line highlight behavior.