Writing a plugin for gatsby-transformer-remark

TL;DR

I wrote a gatsby-transformer-remark plugin to decorate elements with correct Bulma classes and another elements.

This article sums up my process and what I learned along the way.

The code is up at GitHub.

Motivation

As I use Bulma CSS framework in this site, I want to be able to leverage the full power of the framework.

Creating these blog pages from markdown resulted in weirdly (and wrongly) formatted HTML. The headings were missing their class="title is-{depth}" attributes and <blockquote>s and <ul>s were missing their surrounding <p class="content"> tags.

A search around the internets and Gatsby plugin page resulted with zero solutions for my problem. This only meant one thing: I gotta solve it myself.

The outcome

First, let’s have a look at what I was set to achieve.

Given this markdown:

1# Heading level 1

The gatsby-tranformer-remark plugin outputted this HTML:

1<h1>Heading level 1</h1>

And I wanted to have the following for Bulma to style the page correctly:

1<h1 class="title is-1">Heading level 1</h1>

With this problem description I fired up VSCode.

First solution

My first solution was an easy one: just use some regex to match and replace content:

1const bulmafy = post => {
2      let p = post.html
3      let rxs = [
4        { r: /<h1>/gi, s: '<h1 class="title is-1">' },
5        { r: /<h2>/gi, s: '<h2 class="title is-2">' },
6        { r: /<h3>/gi, s: '<h3 class="title is-3">' },
7        { r: /<h4>/gi, s: '<h4 class="title is-4">' },
8        { r: /<h5>/gi, s: '<h5 class="title is-5">' },
9        { r: /<h6>/gi, s: '<h6 class="title is-6">' },
10        { r: /<p>/gi, s: '<p class="content">' },
11        {
12          r: /<ul>([^]+)<\/ul>/gi,
13          s: '<div class="content"><ul>$1</ul></div>',
14        },
15        {
16          r: /<ol>([^]+)<\/ol>/gi,
17          s: '<div class="content"><ol>$1</ol></div>',
18        },
19        {
20          r: /<blockquote>([^]+)<\/blockquote>/gi,
21          s: '<div class="content"><blockquote>$1</blockquote></div>',
22        },
23      ]
24      for (let re of rxs) {
25        p = p.replace(re.r, re.s)
26      }
27      return p
28    }

While this worked okay and did what it should, it felt…wrong.

It’s kinda hacky way to solve the issue at hand and isn’t all that portable.

Attempt #2

From GatsbyJS docs I found this excellent tutorial on how to create a plugin for the gatsby-transformer-remark.

I won’t go into detail about the contents of the tutorial as one can read it by themselves, but the gist of it is “this is how you change AST to HTML”. That’s a great way to introduce one to the world of ASTs and plugins for this system, but it set me a bit of the rail. For a while I thought that making strings from AST is all I can do with this. 🤦🏽‍♂️

After a few evenings of banging my head against the wall trying to recursively render every little case (like having a link inside a block quote to render correctly) I just sort of gave up.

Then I searched around the Remark-ecosystem of thingies and found the remark-html repo that has this part:

In addition, remark-html can be told how to compile nodes through three data properties

Score! 🥳

Now I can just add new data to the nodes and let some other plugin to recursively render it.

For example, here’s block quote:

1visit(markdownAST, "blockquote", (node, ancestors) => {
2    const div = {
3      type: "section",
4      data: {
5        hName: "div",
6        hProperties: { class: "content" },
7      },
8      children: [node],
9    }
10    const parent = ancestors[ancestors.length - 1]
11    const startIndex = parent.children.indexOf(node)
12    parent.children.splice(startIndex, 1, div)
13  })

It creates a new node that will be rendered as a div with attribute class="content" and the contents of the block quote node will be its children.

Then the code replaces the original block quote node with the newly created one in the tree.

What I’ve learned

I haven’t worked with ASTs all that much in the past. This project taught me the ways on thinking about trees which will definitely come in handy in future works.

Now I also have the knowhow to create a Gatsby plugin if I ever need to make a new one.