Skip to main content
View plugin on GitHub
See starters using this

gatsby-remark-highlight-code

Adds stylish cards and syntax highlighting to code blocks in markdown files using the @deckdeckgo/highlight-code Web Component.

This code highlighter is developed with Stencil and use Prism.js under the hood.

The inspiration for the design of the “Macish” cards comes from the amazing carbon, a tool to create and share beautiful images of your source code, and for the “Ubuntu-ish” from the article of Cody Pearce.

Carbon:

Syntax highlighting code block as Carbon card

Ubuntu:

Syntax highlighting code block as Ubuntu card

None:

Syntax highlighting code block

Table of contents

Install

npm install --save gatsby-transformer-remark gatsby-remark-highlight-code @deckdeckgo/highlight-code

How to use

In order to use this plugin, it should be first configured and then loaded at runtime.

Configure

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

Load the component

Stencil components should currently be loaded at runtime (see issue #1724).

For that purpose, load the @deckdeckgo/highlight-code once in one of your pages or components are mounted.

For example add the following in the main file of your website, in your index.js, or in the template of your blog or simply load it where you need it.

async componentDidMount() {
    try {
        const deckdeckgoHighlightCodeLoader = require("@deckdeckgo/highlight-code/dist/loader")
    
        await deckdeckgoHighlightCodeLoader.defineCustomElements(window);
    } catch (err) {
        console.error(err);
    }
}

Language

This plugin supports all languages supported by Prism.js. Nothing particular needs to be specified because the component @deckdeckgo/highlight-code will load them automatically at runtime.

Styling

Code blocks are displayed in stylish cards but the behavior could be customized.

Terminal

Per default, code blocks are going to be displayed in carbon (“Macish like”) container.

It is also possible to use ubuntu (an Ubuntu-like container) or none (no window container).

Such settings can be provided in the configuration of the plugin.

// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-transformer-remark`,
    options: {
      plugins: [
        {
          resolve: `gatsby-remark-highlight-code`,
          options: {
            terminal: 'ubuntu'
          }
        },
      ],
    },
  },
]

Variables

See the @deckdeckgo/highlight-code documentation for the list of CSS4 styling variables.

Showcase

I (David here) use this plugin in the blog of my personal website daviddalbusco.com.

License

MIT © David Dal Busco and Nicolas Mattia