Migrating from gatsby to 11ty

This is the steps that I took to convert my blog from Gatsby to 11ty to give you an idea of what's involved and a strategy to use in the conversion.

Reference

A lot of the static gens are fairly similar; using HTML templating and YAML frontend matter.

My posts and pages were Markdown so they were easy to convert but the layouts being JS Modules, JSX and GraphQL, not so much.

I used the original live site as a reference and kept copies of my content handy.

Installing 11ty

11ty should be installed in a empty folder, if you have other stuff in it, even in a sub-folder, it will likely get confused.

I followed the getting started guide, including creating a basic HTML index page.

[https://www.11ty.dev/docs/getting-started/]

Copying the index

From my live site, I copied my page source content and dumped it in the index page. As my CSS was inline it meant that everything was in the source to correctly display my site.

Clean up

I then went about cleaning up the index file, deleting things that were specific to Gatsby. I kept an eye on the rendered page and console to see that I didn't break anything as I removed things.

Things I removed:

  • Gatsby JS from near the body tag
  • No script tag from body
  • Everything from head except:
    • Description meta
    • title tag
    • google font link
    • style tags
    • viewport meta
    • http-equiv meta
    • CharSet meta
  • removed data-react-helmet="true" from tags

When finished it was just basic HTML, but still with randomised class names, inline styling and styles in head. The served rendered page still matched the live site.

Extracting the CSS

As the CSS was inline and in the head because I used component styling in my Gatsby site. I wanted to move it all to separate SASS files to make it more flexible in the future.

I created a CSS file, a styles.scss file and a _typography.scss file. I cut the content of the typography.js style tag and ran it through an online CSS to SCSS converter [https://css2sass.herokuapp.com/] before pasting it into my _typography.scss file. I loaded that from my styles.scss file.

I did the same for the main styling and added that to styles.scss.

I used the visual studio sass compiler to watch and compile it.

I linked to the compiled css\style.css in the index.html file. 11ty doesn't copy css files to the build folder by default so that needed to be set-up.

Copying CSS files

I created a 11ty config file .eleventy and added this snippet:

module.exports = function(eleventyConfig) {
    eleventyConfig.addPassthroughCopy("css/style.css");
}

This copies the css file into the build folder. I opted for this over copying the whole directory as my SASS files are in their as well.

Cleaning up css naming

I changed the randomly generated class names to meaningful names; only the ones in the index for now. I only had a handful to use but if I had a lot, I would have done this with PHPStorm/WebStorm's refactoring tools.

Cleaning up inline styling

I moved all the inline styling to the SCSS file.

Creating a template

At this point my index file was clean and the served copy still looked like original site. Now I wanted to work on the other pages, so I needed to set up templating.

11ty has plenty of options to choose from. I could have gone for the JS option, but although similar to Gatsby, it still seemed like it would be more of a pain then just porting to HTML templating.

I went with liquid just because that's what I am familiar with as it's used in Jekyll.

I created a new template _includes\default.liquid. I copied over all the generic content from the index.html file. For me that was everything above and below the body tag.

In the default.liquid tag I put the `` tag which is like a placeholder for the main content.

This is now the template for all pages. Each page content will get inserted in the place of the `` tag.

<body>

    

</body>

The index page

I removed the HTML from the index.html page that was now in liquid template.

I added the YAML frontend matter to the top which will tell 11ty to use the liquid template for this page.

---
layout: default
---

MDX pages

I had some simple mostly text pages that were MDX that I needed to convert to markdown.

I deleted everything in the page other then the actual markdown.

I had a component for the title which I added the title to the YAML instead, then used this in the default template.

import { graphql } from 'gatsby'
import Layout from '../components/layout'
import Image from '../components/image'

<Layout title="About">

<Image />

## About me

Some markdown text

Became

---
template: default
title: About me
---

![Pic of me](../images/me.jpg)

## About me

Some markdown text

Then in my default template I put:

<div class="page-header">
  <h1>Migrating from gatsby to 11ty</h1>
</div>

Which would display the title.

Images

I had an image in the markdown. Like the CSS, I needed the images to copy to the build folder _site. So I needed to add some config for that:

module.exports = function(eleventyConfig) {

    eleventyConfig.addPassthroughCopy("images");

    ...
}

Posts collection

My posts were already markdown with YAML so it was easy to get these working.

I put the posts in the root folder as otherwise it would add post/ to the url which I didn't have in the original site.

I needed to add all the posts to a posts collection to create a posts loop.

I will need to get them back into a folder down the line for better organisation.

As with the other MD files, I needed to add a layout, later I would create a posts layout but the default was fine for now.

---
layout: default
title: My blog post title
tags: post
---

The important bit being the tags, the post is now in the tags collection and will be available in a posts loop.

Checking things over

After ending up with a basic site and things looking generally ready, I checked over every page to make sure that everything rendered the same as the original live site.

Very importantly, I checked over the urls to make sure that they matched.

Satisfied, I set-up a Netify deployment.

Summary

It was fairly smooth converting over, partly because of how easy it was to use 11ty. It would have been very easy to switch over from a static gen that used HTML templating.