How I moved from Jekyll to React / Gatsby


Note: This post has been updated for V2 from V1 ( v2.1.37 )

Rather then a step by step, this is more of a guiding hand. The Gatsby docs are very good, much better then smaller frameworks usually are. There are some parts of this process that could do with going into more depth so I’ll cover those areas seperately.

It’s not really a port so much as rebuilding, but coming from the mindset of someone who’s been using Jekyll or other static site generator.

This is different then what your used to with Hugo, Assemble or Jekyll. Which have much more abstraction and are a lot easier to get up and runnng with. Gatsby is definitely more involved, things that are very simple with other templating languages are complex with Gatsby.

But that can be a good thing, it's more flexible and is a good way to get more femiliar with working with React.

There are some ways of working that I really like about Jekyll that I wanted to have with Gatsby too.

Getting started

Install Gatsby

To save some time it's good to start with a starter project, if you are going to have a blog then starting with the blog starter is a good idea - this will save you a lot of manual setup. You’ll have a blog roll, markdown and images setup up out of the box.


The starter blog uses styled components which I like to use now but if you're porting over an exisiting design, you might want to keep what you have.

In Jekyll I had my css file in css/styles.scss and my sass files in _sass In Gatsby I deceided to put it all in a folder called sass, in the src folder. But you can organise it how ever you like.

If your using SASS, you’ll want to install the Gatsby SASS module

You then just import this to your layout file, src/components/layout.js.

import '../sass/style.scss'

Converting liquid templates to JSX

In my Atom editor, I installed a module that allowed me to right click and convert HTML to JSX. This helped by converting class to className but the liquid template references would need to done manually anyway.


Markdown Pages

It’s very much set up with the idea that only posts are markdown - this creates some extra work if you want to write pages in Markdown too. If you have markdown pages and don’t want them to be part of your blog roll, then you’ll need to do something about that.

I wrote a tutorial on how I did this orginally, however I'm now using MDX.


YAML data

I had some YAML data as a source for some pages. The plugin gatsby-transformer-yamldealt with that. I put it in the data folder and in the options for the transformer plugin set that to the data folder.

I was then able to create a page that interates over that data using a GraphQL query.


Jekyll's liquid templates are really nice there isn't really a way to preserve this as working with React components is just really differen't. Same for inclues, you'll need to convert these to React components.


Converting to and getting used to Gatsby was time consuming and Jekyll is pretty darn great. But Gatsby is great if you want to do something more complex or just get more femiliar with React. Essentually, don't take a switch to Gatsby lightly.