How To add Code Highlighting To Gridsome Using Prismjs

#vue #gridsome

Introduction

As developers, we often find ourselves having to share code with other developers in order to illustrate how to do something. Therefore, it is important that we display code in a developer friendly way. A way to to this is using Prismjs.

Even though we can use prismjs from scratch, the leg-work of integrating Prismjs with Gridsome has already been done for us. The @grisome/remark-prismjs already exists and makes adding code highlighting very simple. However, It has it's own issues. This is why I have written this guide so that you avoid some of the pitfalls.

Steps

Installation
Add a Prismjs theme
Add the Plugin to the gridsome configuration

Installation

You will need to install the @gridsome/remark-prismjs and a prismjs theme. For the theme, we will use the the official Primsjs themes but you can use whichever theme you want. In fact, you can even write your own 😉;

npm install prismjs @gridsome/remark-prismjs

Add A Prismjs Theme

Pick a theme from prismjs. If you don't know, open node_modules folder and search for prismjs there. From there pick a theme. Afterwards, import it into the main.js file. Alternatively. you can import it into your main SASS stylesheet (if you use SASS).

//main.js

import 'prismjs/themes/prism.css'

// Prismjs Comes With Other themes. For example, prism-solarizedlight.css'

Add the Plugin to the gridsome configuration

In gridsome.config.js, add the prismjs plugin to a gridsome remark plugin you are using. In the official docs for @gridsome/remark-prismjs, they use the @gridsome/source-filesystem. In my projects, I usually use the @gridsome/vue-remark plugin. Therefore, that is what I'll use in this guide.

In the plugin section of the @gridsome/vue-remark options, add the prismjs plugin as an item in the array.

//gridsome.config.js

module.exports = {
    siteName: 'Site Name',
    plugins: [
        {
            use: '@gridsome/vue-remark',
            options: {
                typeName: 'Post',
                baseDir: './src/posts',
                pathPrefix: '/post',
                template: './src/templates/Post.vue',,
                plugins: ['@gridsome/remark-prismjs'],
            },
        },
    ]
}

That's it. That is the simple way to add code syntax highlighting to your gridsome.

Now, let us deal with the pitfalls that you might face and give possible solutions for them.

Dealing with common issues

1. My Code Blocks Aren't Being Highlighted

This usually a sign that you have done something wrong. Maybe you haven't added a prismjs theme or you have added the prismjs plugin in the wrong place. These are easy mistakes to make and I have done both of them myself.

For example, you might have done this 👇🏾.

//  ❌❌❌❌❌
{
    use: '@gridsome/vue-remark',
    options: {
        typeName: 'Post',
        baseDir: './src/posts',
        pathPrefix: '/post',
        template: './src/templates/Post.vue',
    },
    plugins: ['@gridsome/remark-prismjs'], // this is wrong
}

//✅✅✅✅✅

{
    use: '@gridsome/vue-remark',
    options: {
        typeName: 'Post',
        baseDir: './src/posts',
        pathPrefix: '/post',
        template: './src/templates/Post.vue',,
        plugins: ['@gridsome/remark-prismjs'], // This is Correct
    },
}

2. I Added A New Source, Now Code Highlighting Has Stopped Working

Often, we might need to add another markdown source later on. But as soon we do this, our existing code highlighting breaks. We might wonder: what mistake are we making? However, believe it or not, it's not you. It's the way the @gridsome/vue-remark plugin works.

The issue is that the @gridsome/vue-remark plugin, only takes the plugin configuration for the LAST source. That means that if you have two markdown sources - one for blog posts and the other for tags - only the plugins for the last source will be used.

It appears that @gridsome/vue-remark only uses ONE plugin configuration for all sources at build time. This behaviour isn't specified in the docs, thus, I only found about this in a discussion on Grisome's Github page. This behaviour was observed and the solution provided by kai-oswald. Find out more about it here.

With this knowledge, a working solution is possible. Just add all the plugins to the last @gridsome/vue-remark source that appears in the plugin list.

In our example below 👇🏾, add the @gridsome/remark-prismjs plugin to the tags source (which appears last).

//gridsome.config.js

module.exports = {
    siteName: 'Site Name',
    plugins: [
        {
            use: '@gridsome/vue-remark',
            options: {
                typeName: 'Post',
                baseDir: './src/posts',
                pathPrefix: '/post',
                template: './src/templates/Post.vue',,
            },
        },
        {
            use: '@gridsome/vue-remark',
            options: {
                typeName: 'Tag',
                baseDir: './src/tags',
                pathPrefix: '/tag',,
                template: './src/templates/Tag.vue',,
                plugins: ['@gridsome/remark-prismjs'],
            },
        },
    ]
}

Thing should work now.

3. I Want To Add Options To @gridsome/remark-prismjs, But I Don't Know How To Do It

Again, it is not shown in @gridsome/vue-remark's official docs how to pass options to the plugins it accepts. However, we are given clues elsewhere on how we can do it. These places are on Gridsome's Github page by kai-oswald, gridsome-plugin-remark-codetitle Plugin page, and gridsome-plugin-remark-shiki Plugin page.

If you want to add plugins, the format is one of two way depending on whether you want options or not.

Plugins WITHOUT Options
Plugins WITH Options

1. Plugins WITHOUT Options

You pass the name of the plugins as items in the plugins array option.

// Plugins WITHOUT Options
{
    plugins: ['plugin-1', 'plugin-2']
}

2. Plugins WITH Options

Each plugin is listed in the plugins array option as an array. Within the array, the first item is the plugin name and the second item is its options object.

// Plugins WITH Options
{
    plugins: [['plugin-1', {'options...'}], ['plugin-2', {'options...'}],...]
}

For example, if we want to enable inline code highlighting, which is disabled by default, we need to pass transformInlineCode as true into the options object.

// Enabling inline code highlighting using options

{
    use: '@gridsome/vue-remark',
    options: {
        typeName: 'Post',
        baseDir: './src/posts',
        pathPrefix: '/post',
        template: './src/templates/Post.vue',,
        plugins: [
            [
                '@gridsome/remark-prismjs',
                {
                    transformInlineCode: true,
                },
            ],
        ],
    },
},