Essential Plugins for Gatsby Remark
Tags: react, gatsby
Published: 2020-03-16 03:43:23

---
title: Essential Plugins for Gatsby Remark
published: true
description: Gatsby-Remark is one of those fun plugins that have their own plugins - but there are a lot of them. Here's a list I wrote down a few months ago of plugins I think everyone should use.
tags: React, Gatsby
slug: gatsby-remark-essential-plugins
displayed_publish_date: "2020-03-14"
canonical_url: https://www.swyx.io/writing/gatsby-remark-essential-plugins
---

[Gatsby-Remark](https://www.gatsbyjs.org/packages/gatsby-transformer-remark/) is one of those fun plugins that have their own plugins - but there are a lot of them! (Because [Remark](https://remark.js.org/) has a lot of [plugins](https://github.com/remarkjs/remark/blob/master/doc/plugins.md#list-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:

```js
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](https://www.gatsbyjs.org/packages/gatsby-remark-autolink-headers/?=headers)
>
> 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](https://chrome.google.com/webstore/detail/display-anchors/poahndpaaanbpbeafbkploiobpiiieko?hl=en) 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](https://github.com/remarkjs/remark-autolink-headings) adds the ID and link tags:

```markdown
# Lorem ipsum 😪
## dolor—sit—amet
### consectetur &amp; adipisicing
#### elit
##### elit
```

to

```html
<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](https://using-remark.gatsbyjs.org/hello-world-kitchen-sink/). 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](https://www.gatsbyjs.org/packages/gatsby-remark-prismjs/?=gatsby-remark-prismjs)
>
> Adds syntax highlighting to code blocks in markdown files using [PrismJS](http://prismjs.com/).

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](https://www.swyx.io/writing/svelte-static/), but [gatsby-remark-shiki](https://www.gatsbyjs.org/packages/gatsby-remark-shiki/?=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](https://www.gatsbyjs.org/packages/gatsby-remark-prismjs/#optional-add-line-highlighting-styles), hence I continue to recommend Prism.js.

## `gatsby-remark-copy-linked-file`

> [Link to docs](https://www.gatsbyjs.org/packages/gatsby-remark-copy-linked-files/?=gatsby-remark-copy-linked-file)
>
> 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](https://www.gatsbyjs.org/packages/gatsby-remark-images/?=gatsby-remark-images)
>
> Processes images in markdown so they can be used in the production build.

We all know and love the benefits of [Gatsby Image](https://using-gatsby-image.gatsbyjs.org/). 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](https://www.gatsbyjs.org/packages/gatsby-plugin-sharp/?=gatsby%20sharp) image processing to take advantage of the blur-up performance benefits.

## `gatsby-remark-external-links`

> [Link to Docs](https://www.gatsbyjs.org/packages/gatsby-remark-external-links/?=gatsby-remark-external-links)
>
> 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](https://developers.google.com/web/tools/lighthouse/audits/noopener)), then this plugin does that for you.


## `gatsby-remark-numbered-footnotes`

> [Link to docs](https://www.gatsbyjs.org/packages/gatsby-remark-numbered-footnotes/?=gatsby-remark-numbered-footnotes)
>
> 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:

```markdown
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](https://www.gatsbyjs.org/packages/gatsby-remark-social-cards/?=gatsby-remark-social-cards)
>
> `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](https://www.swyx.io/writing/jamstack-og-images/). 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. 

![https://i.imgur.com/VByhlyE.jpg](https://i.imgur.com/VByhlyE.jpg)

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](https://www.gatsbyjs.org/packages/gatsby-remark-embedder/?=gatsby-remark-embedder)
>
> 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](https://github.com/MichaelDeBoey) 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](https://github.com/remarkjs/remark/blob/master/doc/plugins.md#list-of-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!