
[APIs You Won't Hate](https://apisyouwonthate.com) is a resource for developers who want to learn how to build APIs that are secure, performant, and easy to use. I've been helping to run and maintain the site since roughly the beginning of 2018, when I rebuilt it from a [Jekyll](https://jekyllrb.com/) site to a static site with [Gatsby](https://www.gatsbyjs.com/). This was a huge leap forward for the site - as we were growing the community and adding resources for API developers regularly, it became apparent that we were going to need to support some features that I wasn't really interested in building on top of Jekyll - support for multiple authors, an image optimzation solution.

## Why we chose to move away from Gatsby

So, I built the site with Gatsby, as a visual clone of the Jekyll site. It worked fantastically for us, but as we added more and more articles and authors to the site, it became challenging to maintain, for a variety of reasons.

1.  **Building the site was slow**

    From a clean cache, it could take from 11-15 minutes to build, which meant that regular deployments to our hosting provider were starting to get expensive. It also meant that any debug tasks which required a production build were _intolerably_ slow, and very frustrating.

2.  **Dealing with images was challenging**

    Gatsby has an _amazingly_ clever [strategy for image optimization](https://www.gatsbyjs.com/plugins/gatsby-image/), which involves sending all images used on the site through a pre-build pipeline that makes them accessible via Gatsby's graphql API. This is a foundational part of how Gatsby sites are meant to run, and it gives plenty of options for image loading strategies and optimization approaches.

    What we never quite got right with our implementation was a strategy that would allow authors to upload images to the [apisyouwonthate.com repo](https://github.com/apisyouwonthate/apisyouwonthate.com) with a naming strategy that was sensible.

    Essentially, due to a quirk in our chosen implementation, each image _on the site_ had to have a unique name, and if two images with the same name were uploaded, it caused all kinds of problems. You can imagine that in the course of writing dozens of articles about APIs, there's more than one occasion to create an image called `devtools-network-tab.png`, or `cover.png`, etc.

3.  **Updating the site required too much understanding of Gatsby's underlying platform**

    This basically meant that of the three of us who maintain the site, I was the only one equipped to make significant changes, because I had spent a good deal of time in my day-to-day job building prototypes with Gatsby for [Gymnasium](https://thegymnasium.com). When either of my teammates wanted to make changes to the site, they had a choice: spend hours and hours trying to figure out how the site was configured, struggle to make changes, and submit a PR, _or_ create an issue on GitHub and assign it to me to fix. You can probably guess which happened more often - and looking back, it makes total sense.

4.  **Some lugnut\* had used boostrap to design the layout for the site.**

    <small>

    (\*It was me.)

    </small>

    I used bootstrap out of convenience, and hamfisted it into working with our React site using a couple of libraries and band-aids to get it all "working" properly. This resulted in a near-infinite supply of teeny tiny little layout bugs. These would be fantastic if I needed them for job security... but in practice they were relentless headaches.

## So, what did we gain from moving to Next.js?

Let me be the first to tell you that it's _highly_ likely that everything I accomplished in the site rebuild with Next.js is _possible_ with Gatsby (or your favorite framework). This rebuild sets the stage for a number of features to come, and should make it easier for us to collaborate with new authors, iterate on site designs, and add small features without having to suffer a 10+ minute CI process.

This rebuild gave me a chance to add features, and add some meaningful updates which had been on my plate for quite a long time. Here's a quick summary of some of my favorite features of the new site:

### SEO features

For the first time ever, **Open Graph Images** are embedded correctly across the site - the site uses a fairly simple strategy, grabbing a predetermined cover image of just-the-right-size and embedding that in the header of each page using Open Graph metadata.

<Image
  publicId="posts/migrate-gatsby-to-nextjs-apisyouwonthate-com/og-embeds-work"
  alt="An APIs You Won't Hate article shared on twitter now includes the cover image for the post"
  caption="Rich Open Graph embeds get much more traffic from twitter than the alternative."
/>

We've also got fairly fine-grained control of other SEO metadata, including author names, article titles, and descriptions. Our new implementation will allow us to set Canonical URLs for articles crossposted to APIs You Won't Hate from other sources as well, which makes for better SEO all around. This may also help down the line if we want to add sponsored posts to the site which point to another origin as the canonical home for the information we share.

Want to see how it works? Dive into the [SEO component in the site's source code](https://github.com/apisyouwonthate/apisyouwonthate.com/blob/main/src/components/SEO/SEO.js).

### Contact form & Newsletter signup

We had previously been using [Netlify Forms](https://www.netlify.com/products/forms/) for the site's contact form, but since the new site is hosted on Vercel, that is no longer possible. We're now using [Airtable's API](https://github.com/apisyouwonthate/apisyouwonthate.com/blob/main/src/pages/api/contact/index.js) for the form, which lets us collate all submissions into one place. New entries to this form trigger a routine which notifies site owners that we got a message. We then use Airtable to track responses, and make sure that nothing gets lost in the mail.

This is all made possible by Next.js API routes. These are serverless functions that are magically deployed to the cloud for any route at `/pages/api/[slug]`. We use a similar approach for our Newsletter signup form, which adds contacts to a list on mailjet. You can check out the [API code here](https://github.com/apisyouwonthate/apisyouwonthate.com/blob/main/src/pages/api/newsletter/index.js), and the [newsletter form code here](https://github.com/apisyouwonthate/apisyouwonthate.com/blob/main/src/components/NewsletterForm/NewsletterForm.js).

### Lighthouse scores

Our Lighthouse scores _shot up_ with this reimplementation - and while they're a moving target for a variety of reasons, performance on the site is generally really great. This is helped immensely by [Next.js's Image component](https://nextjs.org/docs/basic-features/image-optimization), which uses a variety of web standards and recommended practices to load the right-size image depending on readers' given device and browser.

<Image
  publicId="posts/migrate-gatsby-to-nextjs-apisyouwonthate-com/lighthouse-scores"
  alt="Lighthouse scores for APIs You Won't Hate: 95 Performance, 100 Accessibility, 100 Best Practies, 100 SEO"
  caption="Near-perfect lighthouse scores were far easier to land thanks to our use of Next.js Image Optimization"
/>

### Search Performance

One of the most important litmus tests available for our site's general performance comes from Google's Search Console. Thankfully, since the site was deployed, we've seen consistent traffic on across all of our pages, with a slight-but-steady increase week to week:

<Image
  publicId="posts/migrate-gatsby-to-nextjs-apisyouwonthate-com/search-results"
  alt="Search Console traffic for APIs You Won't Hate"
  caption="Search Console traffic for APIs You Won't Hate"
/>

Next also made it _far_ easier to generate a `sitemap.xml` for APIs You Won't Hate. In Gatsbyland, we needed to use [`gatsby-plugin-sitemap`](https://www.gatsbyjs.com/docs/how-to/adding-common-features/creating-a-sitemap/), which _is_ configurable, but is generated at _build time._ This meant that debugging sitemap changes took a full 10min+ for _each change_ - which was completely untenable for us.

By contrast, our [sitemap implementation with Next.js](https://github.com/apisyouwonthate/apisyouwonthate.com/blob/main/next-sitemap.js) uses a library called [next-sitemap](https://github.com/iamvishnusankar/next-sitemap). It is _also_ generated at build time, but in a local dev environment builds take only a few seconds, allowing me to nail our sitemap much more quickly.

<Image
  publicId="posts/migrate-gatsby-to-nextjs-apisyouwonthate-com/sitemap"
  alt="Google Search Contole's Sitemap ingestion for APIs You Won't Hate"
  caption="Once everything was right, we pointed Google Search Console to the new sitemap, and verified that everything was working correctly."
/>

### Visual redesign

Because this implementation work gave me an opportunity to rip out the old site's visual design, I was able to make some sorely changes to the site's overall look and feel. I removed Bootstrap and `react-bootstrap`, and used [Chakra UI](https://chakra-ui.com/) for layout building instead. There's a bit of a learning curve with Chakra (like any other UI library), but now that I'm familiar with it, I can build new responsive site pages efficiently and reliably.

Here's some side-by-side comparisons of the old and new site:

**Home Page**

<SimpleGrid columns={[1, 1, 2]} gap={4}>
  <Image
    publicId="posts/migrate-gatsby-to-nextjs-apisyouwonthate-com/home-before"
    alt="Old home page design for apisyouwonthate.com"
    caption="Home page: before"
  />
  <Image
    publicId="posts/migrate-gatsby-to-nextjs-apisyouwonthate-com/home-after"
    alt="New home page design for apisyouwonthate.com"
    caption="After"
  />
</SimpleGrid>

**Book feature page**

<SimpleGrid columns={[1, 1, 2]} gap={4}>
  <Image
    publicId="posts/migrate-gatsby-to-nextjs-apisyouwonthate-com/book-before"
    alt="Old Book feature page for apisyouwonthate.com"
    caption="Book feature page: before"
  />

  <Image
    publicId="posts/migrate-gatsby-to-nextjs-apisyouwonthate-com/book-after"
    alt="New book feature page for apisyouwonthate.com"
    caption="After"
  />
</SimpleGrid>

**Blog landing page**

<SimpleGrid columns={[1, 1, 2]} gap={4}>
<Image
  publicId="posts/migrate-gatsby-to-nextjs-apisyouwonthate-com/blog-before"
  caption="Old blog landing page for apisyouwonthate.com"
  alt="Blog landing page: before"
/>

<Image
  publicId="posts/migrate-gatsby-to-nextjs-apisyouwonthate-com/blog-after"
  caption="New blog landing page for apisyouwonthate.com"
  alt="After"
/>
</SimpleGrid>

## Summary

We've been up and running on Next for a few months now, and everything has been working smoothly. I'm really happy with how this implementation work went, and am really lucky to be able to have a wealth of choices in amazing developer communities that surround JAMstack and SSG tools. Having now built sites and companies with create-react-app, Gatsby, next.js, and Remix Run (keep an eye out for this one!) -- I can say with a high degree of confidence that they are _all_ super tools. You can get your work done in any one of these libraries - often the challenge we face as developers is sticking with our bets long enough to see them through.

Keeping [APIs You Won't Hate](https://apisyouwonthate.com) running and growing has been a forcing function to build a site that is performant and dependable, and affects a large-scale audience... for me, that's more than enough to motivate the work it takes to keep the site running. The community we've built and the knowledge we're sharing are truly fantastic, and it's my privilege to build real sites that people (hopefully) don't hate.


What it's like to migrate a high-traffic website from Gatsby to Next.js


## Why you should link to headings in your articles

You may have come across this pattern in articles and posts on sites you frequent - article headings (think `<h1>`, `<h2>`, `<h3>`, `<h4>`, `<h5>`, and `<h6>` in html) will be be wrapped in links that point to themselves. This allows readers to link to _specific_ headings in your articles, jumping to relevant bits of content without forcing someone to read through an entire article. Generally speaking, it will look something like this:

```html
<a href="#some-unique-id">
  <h1 id="some-unique-id">My first blog post</h1>
</a>
```

The `<a>` tag here has an `href` value of `#some-unique-id` - this is the id of the heading tag. This is based on an HTML [standard defined by the W3C](https://www.w3.org/TR/html401/struct/links.html#h-12.2.3). In short, you can link to any element on an HTML page which has a unique `id` attribute defined, by appending `#[id]` to the end of the URL, like `www.example.com#id-of-the-element`.

## This is tricky with Markdown and MDX

In most static site generators and JAMStack frameworks which allow you to use Markdown and MDX to generate content, the goal is simple: give authors a _very_ simple way to author content using Markdown syntax. The unfortunate side effect in this case is that there's not a way to specify IDs for the headings in Markdown posts (at least, not one that I'm aware of).

A sample markdown post might look like this:

```md
---
title: Hello, world
---

# A fish called wanda

In this essay, I will explain the difference between...
```

This results in the following output:

```html
<h1>A fish called wanda</h1>
<p>In this essay, I will explain the difference between...</p>
```

Fantastic! That's a nice, easy way to write, but there's not a way to add an id to the heading tag. At least, not out of the box. This is where MDX's plugins come in handy.

## Automatically linking to headings in your mdx posts with rehype plugins

> _Note: This tutorial assumes you're using MDX with NextJS, althought it may be applicable to other systems. Feel free to [send me](https://twitter.com/irreverentmike) any hurdles you encounter with other frameworks, and I'll try to document them here._

### Step 1: Generate IDs for all headings automatically with rehype-slug

[`rehype-slug`](https://github.com/rehypejs/rehype-slug) is a plugin that works with MDX, and will automatically generate IDs for your headings by generating a slug based on the text they contain.

1. Install `rehype-slug` in your project by running `npm install --save rehype-slug` or `yarn add rehype-slug`

2. Add `rehype-slug` to the list of rehype plugins MDX uses. In the case of next.js sites, it is likely wherever you call `serialize()` from `next-mdx-remote`.

```jsx
import rehypeSlug from 'rehype-slug';

// ...

const options = {
  mdxOptions: {
    rehypePlugins: [
      rehypeSlug, // add IDs to any h1-h6 tag that doesn't have one, using a slug made from its text
    ],
  },
};

const mdxSource = await serialize(post.content, options);

// ...
```

**Note:** My site uses `serialize()` in several places, so I extracted `options` to its own file. This avoids repeated code, and allows me to manage my plugins for MDX from one place.

At this point, if you fire up your dev environment, and use your browser devtools to inspect any of the headings generated from markdown for your site, they should all have an `id` property added. For the example above, you'd see:

```html
<h1 id="a-fish-called-wanda">A fish called wanda</h1>
```

We're halfway there - you can now link to `www.example.com#a-fish-called-wanda`, and the browser will automatically scroll to the heading.

### Step 2: use MDXProvider to customize the way heading tags render

[MDXProvider](https://mdxjs.com/docs/using-mdx/#mdx-provider) is a wrapper component which allows you to customize the way your MDX renders by providing a list of `components`.

This step will depend heavily on the UI frameworks you've chosen for your site - I use [Chakra UI](https://chakra-ui.com/) for my nextjs site, but you can use whatever you like - [tailwindcss](https://tailwindcss.com/), [Material UI](https://mui.com/), etc will all have similar parallels.

Here's a simplified version of the code, which I'll show just for `<h1>` - you'd want to extend this for all title tags, i.e. `<h1>` through `<h6>`:

```jsx
import Link from 'next/link';

const CustomH1 = ({ id, ...rest }) => {
  if (id) {
    return (
      <Link href={`#${id}`}>
        <a>
          <h1 {...rest} />
        </a>
      </Link>
    );
  }
  return <h1 {...rest} />;
};

const components = {
  h1: CustomH1,
};

// this would also work in pages/_app.js
const Layout = ({ children }) => {
  return <MDXProvider components={components}>{children}</MDXProvider>;
};
```

### Doing it with Chakra UI

Like I mentioned above, my site uses Chakra UI to compose page layouts. I've added a bit of customization to links on my site - including a hover behavior which adds a nice `#` character before headings when they're hovered over. If you're curious about [my implementation](https://github.com/mbifulco/blog/pull/577) with Chakra UI, it looks a bit like this:

```jsx
import NextLink from 'next/link';
import { Link, Heading } from '@chakra-ui/react';

const CustomHeading = ({ as, id, ...props }) => {
  if (id) {
    return (
      <Link href={`#${id}`}>
        <NextLink href={`#${id}`}>
          <Heading
            as={as}
            display="inline"
            id={id}
            lineHeight={'1em'}
            {...props}
            _hover={{
              _before: {
                content: '"#"',
                position: 'relative',
                marginLeft: '-1.2ch',
                paddingRight: '0.2ch',
              },
            }}
          />
        </NextLink>
      </Link>
    );
  }
  return <Heading as={as} {...props} />;
};

const H1 = (props) => <CustomHeading as="h1" {...props} />;
const H2 = (props) => <CustomHeading as="h2" {...props} />;
const H3 = (props) => <CustomHeading as="h3" {...props} />;
const H4 = (props) => <CustomHeading as="h4" {...props} />;
const H5 = (props) => <CustomHeading as="h5" {...props} />;
const H6 = (props) => <CustomHeading as="h6" {...props} />;

const components = {
  h1: H1,
  h2: H2,
  h3: H3,
  h4: H4,
  h5: H5,
  h6: H6,
};

// ...etc - components is passed to MDXProvider in my Layout component
```

## The Result

The result is what you see on [this page](/posts/mdx-auto-link-headings-with-rehype-slug#automatically-linking-to-headings-in-your-mdx-posts), and any of the other posts on my site! Every heading on my markdown pages contains an ID, and is wrapped in a link to itself. This makes it easy for readers to tap on the link to send it to their URL bar, or to right-click/long-press and copy a link to the part of the article they want to link to.

The final markup looks a bit like this:

```html
<a href="#a-fish-called-wanda">
  <h1 id="a-fish-called-wanda">A fish called wanda</h1>
</a>
```

I hope you found this helpful! If you run into any trouble, feel free to [drop me a line on twitter](https://twitter.com/irreverentmike). Beyond that, I'd love it if you shared this post with someone who you think could benefit from it.

## Auto-linking headings with other frameworks

- Generic **HTML and JavaScript** - if you're looking for a platform-agnostic solution, you may want to check out this CSS Tricks Article, [On Adding IDs to Headings](https://css-tricks.com/on-adding-ids-to-headers/)
- **Jekyll** - a reader was kind enough to send me a tutorial for the same functionality in [Jekyll](https://jekyllrb.com/). Check it out on [David Darnes](https://twitter.com/DavidDarnes)' site here: [Adding heading links to your Jekyll blog](https://darn.es/adding-heading-links-to-your-jekyll-blog/)
- **11ty** - There doesn't seem to be a standard practice for this pattern with [11ty](https://11ty.dev/), but there was a great discussion on ways this might be implemented with plugins and shortcodes in this GitHub Issue: [Support generating IDs for headings, for section direct links ](https://github.com/11ty/eleventy/issues/1593)
- **Gatsby** - [Gatsby](https://www.gatsbyjs.org/) has a plugin which supports this behavior, called [gatsby-remark-autolink-headers](https://www.gatsbyjs.com/plugins/gatsby-remark-autolink-headers/)

## More reading

If you found this helpful, you may also be interested in:

- [JavaScript Tips: Nullish Coalescing (??)](https://mikebifulco.com/posts/nullish-coalescing-javascript)
- [JavaScript Tips: Using Array.filter(Boolean)](https://mikebifulco.com/posts/javascript-filter-boolean)
- [MDX: I should have done this sooner](https://mikebifulco.com/posts/moving-to-mdx)


#nextjs: 2 posts tagged

What it's like to migrate a high-traffic website from Gatsby to Next.js

Next.js with MDX tips: Provide shortcuts to article headings

.css-1fb0br2{color:#A0AEC0;}#nextjs: 2 posts tagged

#nextjs: 2 posts tagged