gridsome-plugin-remark-shiki

Syntax highlighter for markdown code blocks using shiki

Install

yarn add gridsome-plugin-remark-shiki
npm install gridsome-plugin-remark-shiki

Usage

With a single markdown source

Add syntax highlighter to a single markdown source using the given options:

module.exports = {
  plugins: [
    {
      use: '@gridsome/source-filesystem',
      options: {
        path: 'blog/**/*.md',
        route: '/blog/:year/:month/:day/:slug',
        remark: {
          plugins: [
            [ 'gridsome-plugin-remark-shiki', { theme: 'nord', skipInline: false } ]
          ]
        }
      }
    }
  ]
}

With all markdown sources

Add syntax highlighter to all markdown sources, but skip inline code:

module.exports = {
  plugins: [
    {
      use: '@gridsome/source-filesystem',
      options: {}
    }
  ],

  transformers: {
    remark: {
      plugins: [
        [ 'gridsome-plugin-remark-shiki', { theme: 'nord', skipInline: true } ]
      ]
    }
  }
}

Using custom themes

Use custom themes with the syntax highlighter:

const shiki = require('shiki')

const customTheme = shiki.loadTheme('./static/custom-theme.json')

module.exports = {
  plugins: [
    {
      use: '@gridsome/source-filesystem',
      options: {
        path: 'blog/**/*.md',
        typeName: 'Post',
        remark: {
          plugins: [
            [ 'gridsome-plugin-remark-shiki', { theme: customTheme, skipInline: true } ]
          ]
        }
      }
    }
  ]
}

With @gridsome/vue-remark

module.exports = {
  plugins: [
    {
      use: '@gridsome/vue-remark',
      options: {
        typeName: 'BlogPost',
        baseDir: './blog/posts',
        template: './src/templates/BlogPost.vue',
        plugins: [
          [
            'gridsome-plugin-remark-shiki',
            { theme: 'nord', skipInline: true },
          ],
        ],
      },
    },
  ],
};

Features

The following options are available for this plugin:

{
  // declare a theme for syntax highlighting
  theme: 'nord',
  // skip the inline code elements (default: false)
  skipInline: true,
  // display language of the highlighted code (default: false)
  showLanguage: true,
  // display line numbers (default: false)
  showLineNumbers: true,
  // enable line highlighting (default: false)
  highlightLines: true,
  // set aliases
  aliases: {
    dockerfile: 'docker',
    yml: 'yaml'
  }
}

Display language

When showLanguage is true, the plugin will add a block displaying the language as follows:

<div class="code-metadata"><span class="language-id">js</span></div>
<pre class="shiki" tabindex="0"><code><!-- highlighted code --></code></pre>

You can write CSS to customize how you want to display code-metadata, e.g.,

.code-metadata {
  user-select: none; /* disable copying metadata while copying the code from the code block */
  margin-bottom: 1ch;
}

.code-metadata .language-id {
  padding: 0.25em 0.5em;
  background-color: blue;
  color: white;
  border-radius: 0.25em;
}

Note that the language will be shown only when it is specified in the codeblock metadata.

Display line numbers

When showLineNumbers is true, the plugin will display the line numbers alongside each line.

<pre class="shiki" tabindex="0">
  <code>
    <span class="line">
      <span class="line-number" aria-hidden="true">1</span>
      <span>console.log('Hello, world');</span>
    </span>
    <span class="line">
      <span class="line-number" aria-hidden="true">2</span>
      <span>console.log('This codeblock is displayed with line numbers!');</span>
    </span>
  </code>
</pre>

You can write custom CSS to control how the line numbers would look, e.g.,

.shiki .line .line-number {
  display: inline-block;
  user-select: none; /* disable copying line numbers while copying the code from the code block */
  padding-inline-end: 2ch;
  text-align: right;
  opacity: 0.6;
}

Note that line numbers will not be displayed for codeblocks of single line.

Highlight lines

When highlightLines is true, you can specify the lines to highlight in code block's metadata. This could be a series or range of line numbers, e.g.,

```js {2}
console.log('Hello, world!')
console.log('Behold the highlighted line!')
```

```js {1,3-4}
console.log('Hello, world! This is highlighted line!')
console.log('Your code is not your life.')
console.log('Behold another highlighted line!')
console.log('And yet another highlighted line!')
```

Aliases

If Shiki does not support highlighting your language or the language identifier that you used is different from what Shiki uses, you can alias them as follows to force syntax highlighting.

aliases: {
  dockerfile: 'docker',
  yml: 'yaml'
}

Dark Mode support

Shiki provides multiple ways to support Dark Mode. Refer to the documentation here: https://github.com/shikijs/shiki/blob/main/docs/themes.md#dark-mode-support