How I moved from Jekyll to React / Gatsby

Rather then a step by step, this is intented to be 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. It involves using React components over those nice templating languages. So you have to be comfortable building React components or willing to learn that.

So this is a few nodes on trying to preserve a few ways of doing things form Jekyll, like markdown pages and using YAML ans a datasource.

Getting started

Install Gatsby

To save some time, create your new Gatsby project using the blog starter repo. This will save you a lot of manual setup. You’ll have a blog roll, markdown and images setup up out of the box so you’ll save yourself some time.


The starter blog uses styled components. You might want to switch over to this but if you want to at least to start with keep your CSS or SASS file, then it’s very simple.

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, src/layouts/index.js

Converting liquid templates to JSX

In my Atom, I installed the react 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. 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. This was the tricky part as it involved needing to understand some GraphQL which Gatsby uses.

Here’s a seperate tutorial on that.

YAML data

I had some YAML data as a source for some pages. The plugin gatsby-transformer-yaml dealt 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.

I’ll do a tutorial on this too.


The beauty of Jekyll likes in the liquid templates and likely is what you’ll miss the most in using React. I surmise that anyone converting is doing to because they know or want to know react.

Creating a react layout from a liquid template is a rebuild.


Creating includes was a matter of creating react components, then using props to pass the custom data. This is quite different to liquid templates, it’s just a matter of taking a include and converting it manually to react components. So you need to understand react components. What I’m saying it this is very much rebuilding in another framework and not a easy port.

Kyle Mathews

Written by Zack Allnutt who works as a freelancer in the UK, building useful things in PHP and Javascript.