Essential Plugins for Gatsby Remark

Gatsby-Remark is one of those fun plugins that have their own plugins - but there are a lot of them! (Because Remark has a lot of plugins)

Here’s a list of plugins I think everyone should use, and what they do.

Bottom Line Up Front

I’d recommend a gatsby-config.js that looks like:

plugins: [
    {
      resolve: `gatsby-transformer-remark`,
      options: {
        plugins: [
          'gatsby-remark-autolink-headers',
          'gatsby-remark-prismjs',
          'gatsby-remark-copy-linked-file',
          'gatsby-remark-external-links',
          'gatsby-remark-images',
          'gatsby-remark-numbered-footnotes',
          'gatsby-remark-social-cards',
          'gatsby-remark-embedder'
      }
    }
  ]

(Note I’ve omitted all options for these plugin-plugins, but you’re probably going to want to specify some options for some of these)

Plugins

gatsby-remark-autolink-headers

Link to docs

Adds GitHub-style hover links to headers in your markdown files when they’re rendered.

This one is first because it is SO important to user experience. I link to anchor tags all the time (using the Display Anchors browser extension), and it is a pain to try to link to a specific part of a long blog post with a header that doesn’t have an ID or a handy link for the user to copy! So remark-autolink-headings adds the ID and link tags:

# Lorem ipsum 😪
## dolor—sit—amet
### consectetur & adipisicing
#### elit
##### elit

to

<h1 id="lorem-ipsum-"><a href="#lorem-ipsum-" aria-hidden="true"><span class="icon icon-link"></span></a>Lorem ipsum 😪</h1>
<h2 id="dolorsitamet"><a href="#dolorsitamet" aria-hidden="true"><span class="icon icon-link"></span></a>dolor—sit—amet</h2>
<h3 id="consectetur--adipisicing"><a href="#consectetur--adipisicing" aria-hidden="true"><span class="icon icon-link"></span></a>consectetur &#x26; adipisicing</h3>
<h4 id="elit"><a href="#elit" aria-hidden="true"><span class="icon icon-link"></span></a>elit</h4>
<h5 id="elit-1"><a href="#elit-1" aria-hidden="true"><span class="icon icon-link"></span></a>elit</h5>

The Gatsby version of this plugin also adds some nice hover styling with a nicer link icon, which you can see in the Kitchen Sink demo. Note that GitHub works like this by default.

This quite frankly was a straight up design flaw in Markdown and I flatly refuse to write any Markdown content without these enhancements.

gatsby-remark-prismjs

Link to docs

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

This one is key for developer blogs. As a developer, you can pry syntax highlighting from my cold, dead, carpal tunnel ridden hands. Please don’t make me read your blog without syntax highlighting.

Note, however, that PrismJS highlighting is done clientside, which will add ~19kb to your JS bundle so that you can do dynamic highlighting (i.e. if you need your reader to edit code and the highlighting to change accordingly). If you only need static highlighting, then you could look into only doing it at build time and sending no JS down the wire. I have used shiki from the Vue ecosystem, but gatsby-remark-shiki seems less popular.

However, this tradeoff is not free, because the syntax highlighted HTML that gets generated is bulkier, and you lose some very nice features like line highlighting, hence I continue to recommend Prism.js.

gatsby-remark-copy-linked-file

Link to docs

Copies local files linked to/from Markdown (.md|.markdown) files to the root directory (i.e., public folder).

This one is important because it lets you colocate your markdown with other resources, for example static files and images, instead of splitting them up into a “content” folder and a “static” and a “images” folder - resulting in an append-only folder of jumbled content where you don’t know what belongs to what.

So instead of this:

/content
  /my-blog-post.md
/static
  /images
    /my-blog-post-image1.png
  /brochure.pdf

You get:

/content
  /my-blog-post
    /index.md
    /my-blog-post-image1.png
    /brochure.pdf

And Gatsby copies files out to the appropriate folder at build time.

gatsby-remark-images

Link to docs

Processes images in markdown so they can be used in the production build.

We all know and love the benefits of Gatsby Image. Related to the above, when you reference an image from your markdown, you don’t just want to load a simple image, you want to run it through Gatsby Sharp image processing to take advantage of the blur-up performance benefits.

gatsby-remark-external-links

Link to Docs

Adds the target and rel attributes to external links in markdown.

This one is pretty simple - by default, Markdown links just translate to <a href="https://mylink.com"> links which cause people to navigate off your site. For some people this is desired behavior, but if you want Remark to automatically add target="_blank" and rel="nofollow noopener noreferrer" (for security), then this plugin does that for you.

gatsby-remark-numbered-footnotes

Link to docs

This is a plugin for gatsby-transformer-remark that converts footnote reference links to sequential numbers.

Footnotes are great! They let you add extra context without cluttering your message. You can write footnotes in Markdown like so:

This is normal body copy.[^also] It includes a couple footnotes.[^thing]

[^also]:
  This is a footnote.

[^thing]:
  This is another footnote.

And it looks like this (note I don’t have this setup on my personal site yet):

This is normal body copy.[^also] It includes a couple footnotes.[^thing]

[^also]: This is a footnote.

[^thing]: This is another footnote.

Pretty nice to read!

gatsby-remark-social-cards

Link to Docs

gatsby-remark-social-cards iterates over your markdown files and automatically generates graphical representations of the frontmatter data! It’s highly customizable and can help increase your click rates.

As I blogged recently, OG Images are your site’s calling card. Plain and simple, people read your social cards way more than your post content, so it ought to be appealing and informative instead of repetitive.

This plugin is well tested and has every feature you could want to transform Markdown frontmatter to your social unfurl card of choice.

gatsby-remark-embedder

Link to Docs

Gatsby Remark plugin to embed well known services by their URL.

I’ll just let them explain:

Trying to embed well known services (like CodePen, CodeSandbox, GIPHY, Instagram, Lichess, Pinterest, Slides, SoundCloud, Spotify, Streamable, Twitter or YouTube) into your Gatsby website can be hard, since you have to know how this needs to be done for all of these different services.

gatsby-remark-embedder tries to solve this problem for you by letting you just copy-paste the link to the pen/player/sandbox/tweet/video you want to embed right from within your browser onto a separate line (surrounded by empty lines) and replace it with the proper embed-code.

It’s been a pleasure watching this plugin grow - the maintainer Michael is pretty diligent about adding more and more content types like SoundCloud and CodePen. These are simple components that we should not have to rewrite every time, and help make our blogposts a lot more interactive so that people don’t have to leave our site to enjoy non-simple-text content.

Conclusion

You can create really great reading experiences with these plugins, and get a lot of mileage out of remark. They seem like relatively conservative choices which, should you have to move on from Gatsby or Remark in future, you could adapt and make work again without heavy rewriting of content. This is the promise of Markdown, after all.

I do wish more of these were framework agnostic, because all this work going into gatsby-remark plugins could have just been remark plugins and therefore usable by others. But of course there are some Gatsby specific concerns and opportunities that these plugins can take advantage of. But I worry that the community is unneccesarily splintered as a result.

What other Gatsby Remark plugins do you particularly like? Let me know in replies/comments!