Building your own blog with Gatsby and Novela

By Brad Tiller, Marketing and Growth
16 minute read

This article will teach you how to start publishing articles online with Novela, a free theme designed by Narative for Gatsby websites.

We created Novela as an easy way for anyone to start hosting their writing online, without having to worry about designing a site from scratch. Novela provides a fast, modern reading experience across all devices while keeping you in control of your content.

See a live preview of Novela at

If you want to get started right away, you can skip ahead to Getting started. But before that, I want to answer a common question:

Why should I host my own content?

Services like Medium and WordPress allow you to simply create an account and start posting online in minutes. Hosting your own content is a bit more complicated, so why do it?

While you still own the content you post to third-party platforms, you sacrifice a lot of control over how your content is presented and what you can do with it in the future.

When we decided to stop posting on external platforms like Medium and build our own site for hosting articles, we did so because:

  1. We wanted to provide a better reading experience. Hosting content ourselves allowed us to add features we care about (like dark mode) and more precise control over how text and media are presented in each piece.

  2. We believe it’s important to keep control of content. Platforms have their own incentives for hosting content that could conflict with your own. Medium, a company particularly known for changing up its business model in ways damaging to its partners, now heavily advertises its subscriptions on top of authors’ content and in members’ inboxes. Even if your goal is to provide freely-accessible content, Medium promotes a different message.

By the end of this article, you’ll have your first post published on your new Novela website. But if you want to switch to a different Gatsby theme later, or build your own site from scratch and move your content there, you’ll be able to do that too — because you’re in direct control of the files your content is within.

Getting started

If you’re already familiar with Gatsby and Git, you likely don’t need this guide; you can jump straight to the GitHub repository for Novela and check the documentation there to get started.

If you’re new to it all, this guide will cover the simplest way to see your Novela site up-and-running: using a GitHub repository and Gatsby Cloud.

There are a few account creations and downloads necessary to complete the process, so it’s faster to get them out of the way at the start. You’ll need:

Set up your Gatsby on your computer

To create a new website using the Novela Gatsby Starter, you’ll create a copy of the starter on your computer and use it to build your new website first on your own machine, and then later upload it to the web.

Never heard of Gatsby? It’s a toolkit for creating extremely fast websites and apps that lets you pull data from almost any source. Novela is a theme designed exclusively for Gatsby websites, so it requires Gatsby to work. You can learn more at

Gatsby’s article on setting up your development environment will tell you exactly what you need to download for your operating system and teach you everything needed to create a Gatsby website copy using the command line — a text-based interface.

An example of entering the "gatsby --help" command in a command line to receive options for Gatsby.
An example of entering the "gatsby --help" command in a command line to receive options for Gatsby.

If you use a Mac, you’ll open the Terminal app that’s built into macOS. If you’re using Windows, you can use Git Bash, which is included in the Git for Windows download.

Create a new repository on GitHub

Login to your GitHub account and create a new repository, which will host all of the files for your site. We’ll be using novela-sample as the repository name for this guide, but you can name yours whatever you want. You don’t have to add anything to it yet.

In the next step you’ll create a clone of gatsby-starter-novela on your local machine, which you’ll eventually upload to the empty repository you just created.

Authenticate Git with GitHub

Before you can commit updates to your GitHub repository using the command line, you’ll need to authorize Git by storing your GitHub login credentials.

To prove to GitHub that you’re the one pushing updates, you can generate a unique SSH key using the command line. Follow GitHub’s instructions for your platform on this page and then paste your generated SSH key into the keys page in your GitHub settings.

Create a clone of Novela Gatsby Starter

Next you’ll use the command line to create a clone of the gatsby-starter-novela repository and run it locally on your computer.

1gatsby new novela-sample

This command tells Gatsby to create a new project, novela-sample (replace with your own directory name) from a copy of the Gatsby Starter Novela project on GitHub by downloading all of the files to your machine.

You can confirm that the site was cloned correctly running the command:

1gatsby develop

This will run a development version of your Gatsby website on your machine, visible in your web browser by visiting localhost:8000. You should see the Novela theme with its default content displayed.

End the development mode by returning to the command line and pressing Ctrl+C to end the current process. (This is how you’ll usually stop any running processes in the command line.)

When you run gatsby develop, it generates a new build of your site each time, which takes a few moments. You can save the current build with gatsby build and then use gatsby serve to view it at localhost:9000 without having to rebuild.

Upload your project to GitHub

First update the URL for the remote repository so that any changes we make publish to your own GitHub repository, instead of the original Gatsby Starter repo.

1git remote set-url origin

This will change the origin repository from to your own repository. You can confirm the origin URL by entering the command git remote -v. You should see:

1origin (fetch)
2origin (push)

Finally, we need to run two commands to commit our changes and then push them to GitHub.

1git commit -am "Commit message"

commit -a searches the directory for any changed files and automatically adds them to the next commit. All commits require a commit message that explains why files were updated in the format of m "Commit message". In this case you could simply write “cloning starter repo.”

Then simply run the git push command to push your files to the repository you previously created and linked.

1git push

Visit and open your repository and you should see all of your files successfully uploaded!

Create your site in Gatsby Cloud

Login to the Gatsby Cloud account you created earlier and create a new site. This will allow you to generate a live online preview of your Novela site (or any other Gatsby site).

When asked, select “I already have a Gatsby site” — because you have the project you just cloned! Link the GitHub repository you just uploaded your clone of Novela starter to.

Linking a new GitHub repository in Gatsby Cloud
Linking a new GitHub repository in Gatsby Cloud

You can skip the integrations step in Gatsby Cloud for now, and finish creating your site. Now you can use Gatsby Cloud’s preview feature to see your copy of Novela live at the preview URL or in the Preview section of the dashboard:

The preview dashboard inside of Gatsby Cloud
The preview dashboard inside of Gatsby Cloud

However, you’ll still only see the default title, author and post built into the Novela theme. To update these, you’ll need to open the local folder you saved your Gatsby project to and open gatsby-config.js in your code editor.

Adding a title, description and social links

At the top of gatsby-config.js you’ll see:

1siteMetadata: {
2 title: `Novela by Narative`,
3 name: `Narative`,
4 siteUrl: ``,
5 description: `This is my description that will be used in the meta tags and important for search results`,
6 hero: {
7 heading: `Welcome to Novela, the simplest way to start publishing with Gatsby.`,
8 maxWidth: 652,
9 },
10 social: [
11 {
12 name: `twitter`,
13 url: ``,
14 },
15 ]

  • Title: The title of your site, which will be used to generate the <title> tags that appear in browser tabs and search results.

  • Name: Will be shown in the footer next to the copyright date.

  • Site URL: The URL of your site. You can change this at any point, so don’t worry if you’re not sure yet — just leave it as-is.

  • Description: Will be used as your site’s description in search results, social shares and other places around the web.

  • Hero: The text written here will appear in the large area above articles on your Novela site’s homepage, called the “hero” section. You can adjust the maxWidth property to tweak the maximum width of the hero column in pixels for more precise control of how your title is displayed.

  • Social: Controls which social media icons will appear in the site footer, and which URLs they will link to. You can remove unwanted links by simply deleting the lines from the file (including the brackets and commas above and below), or change them to a different service that you do use. The complete list of supported names and icons can be found here.

Once you’re satisfied with the changes, save gatsby-config.js in your text editor, return to your command line and commit all your saved changes once again:

1git commit -am "Updated metadata"

Remember, git commit -a commits any changed files in your project directory. If you’ve made more changes outside your gatsby-config.js file, they’ll be committed too. When changed files are committed, they’ll be pushed to your repo when you use the git push command.

You might not always want to commit all of your changes at once. To see a list of which changes are currently tracked or untracked, you can run the git status command and then use git add to track changed files one at a time. Then use git commit -m "Commit message" to commit any tracked files while leaving untracked files out of the commit.When you’re done, use git push to push all of your committed changes to your GitHub repo. Your changes will appear almost immediately on your live Gatsby Cloud preview.

Adding content to your site

You have a fully functional Gatsby project running Novela! You can now add yourself and others as authors and start adding your own posts (along with deleting the default content that’s there).

You have two options for how to host your content:

  • As local files in your Git repo: To add authors and create posts, you’ll create new folders and text files in your local project directory on your machine, then push updates to GitHub using the command line like you’ve been doing so far.

  • Add Contentful as a data source. Contentful is a “headless” content management system, meaning it’s designed to only store content that appears inside a site (like text and images), and not the rest of the code that displays or styles it. If you use Contentful as a data source, you’ll log into your Contentful dashboard to add authors and edit posts.

You can choose to start with local files and switch to Contentful later, or vice versa. Or you can switch to something else entirely — that’s one of the benefits of keeping control of your content.

Adding authors and posts with local files

First you’ll want to delete the example authors included in the starter package (RIP us) and replace them with your own. All author information is stored in content/authors/authors.yml.

Open authors.yml in your code editor. There are two authors included in the sample file, but you can have as few or as many as you want.

1- name: Dennis Brotzky
2 bio: |
3 Written by You. This is where your author bio lives. Share your work, your
4 joys and of course, your Twitter handle.
5 avatar: ./avatars/dennis-brotzky.jpg
6 featured: true
7 social:
8 - name: github
9 url:

Here’s how each field works:

  • Name: The name that will appear for this author on posts and on their author page.

  • Bio: This description will be included on the author page and on the homepage for the user that’s featured.

  • Avatar: The location of the author’s avatar, used as their profile photo across the site. Avatar images are stored in in content/authors/avatars — you can add your own photo and delete the sample photos that are included.

  • Social: Adds social icons to the author page with links to the included sites. The supported sites are the same ones supported in gatsby-config.js, which can be seen here.

  • Featured: When featured: true is included for an author, it sets their avatar and bio to appear on your site’s homepage. At least one author must include featured: true, even if you only have one author in your authors.yml file.

Save your authors.yml file when you’re done.

Next, open the existing sample post and set yourself as the author. You’ll find it in content/posts/2020-01-01-my-first-post-using-novela-by-narative.

Start by opening the index.mdx file in your text editor. You’ll see the following at the top:

2title: My first post using Novela by Narative
3author: Dennis Brotzky
4date: 2019-04-30
5hero: ./images/hero.jpg
6excerpt: With the growing community interest in Gatsby, we hope to create more resources that make it easier for anyone to grasp the power of this incredible tool.

With Novela, each post is stored as an index.mdx file within its own folder under posts. At the top of each index.mdx file, you’ll need to include the following fields for each post:

  • Title: The title of the post.

  • Author: The author of the post. You can add multiple authors to a post by separating their names with commas. Change the author of this post to match one of the authors you added to authors.yml.

  • Date: The date that will appear with the post, formatted as YYYY-MM-DD

  • Hero: The location of the “hero” image which will be shown attached to the post across your site, in social media shares and elsewhere. Your folder for each post should also include an images folder to include the hero image and any other images you want to display in your posts. We recommend an image width of at least 1200px.

  • Excerpt: A short description of the post that will appear across your site, in search results and across the web. Limited to 140 characters.

There are also optional fields you can add if you wish, each on their own line:

1secret: true

secret: true will hide the post from any listings on your site, but still keep it visible via URL.

1slug: your-own-slug

The “slug” is the part of the URL that points to your post (e.g. Novela will automatically generate a slug for your post based on its title, but you can override it by including it after slug:.

The content of a post goes directly underneath the header. This sample post also contains examples of how to format text in your posts using Markdown, and embedding images with the following block of HTML:

1<div className="Image__Small">
2  <img
3    src="./images/article-image-2.jpg"
4    title="Logo Title Text 1"
5    alt="Alt text"
6  />
  • Image__Small will display the image within the same column size as the article’s text. Use Image__Medium and Image_Large for wider and full-screen images respectively

  • src points to the location of the image file, in this case within the same post’s “images” folder; this can also point to another directory or a URL

  • title contains a title for the image and will be displayed when users hover over an image

  • alt text describes the image to sources like search engines and screen readers, so it should describe the contents of the image with language your audience would use and search for

It’s worth keeping this post as a reference for now, so instead of deleting it, add secret: true to a new line in the top section, and change the author to an author you added to authors.yml. Then save the file.

Next, let’s add a new post. Create a new folder in content/posts with any name you want. We recommend leading with the date followed by the title of the post, e.g.


This folder won’t appear in the URL. Novela will generate a URL for each post automatically based on its title.

Within your new folder, create an images folder to host your post’s hero image and any others you want to include. If you don’t have one ready, use this one for now!

Then create a new text file, save it as index.mdx in the post directory you just created, and fill out the required fields. Be sure to include the --- before and after!

4date: YYYY-MM-DD
5hero: ./images/hero.jpg

Underneath, you can write the contents of your post in the same Markdown formatting used in the example post. Feel free to copy code directly from the sample post into yours to try it out.

Once you’re happy with your post, save the index.mdx file for your new post and return to the command line to publish all of the changes you just made.

If you haven’t tried it yet, run git status to see all the documents that still need to be committed. Then you can either:

  • add all untracked files with git add . or choose which files to commit with git add filename, then commit with git commit -m "Commit message", OR

  • add and commit everything like before with git commit -am "Commit message"

Then run git push to push your changes to Gatsby Cloud and GitHub, and you should see your Gatsby Cloud preview update with your new author information and posts.

Example after updating authors and posts, set to dark mode (using the toggle in the top-right).
Example after updating authors and posts, set to dark mode (using the toggle in the top-right).

Now you know everything you need to add new posts to your Novela site with Gatsby and Git!

The next section will cover using Contentful as a data source for content like authors and posts. If you’d prefer to get your blog online using local files, skip to Hosting your finished site.

Adding authors and posts with Contentful

Novela also supports using Contentful, a content management system, as a data source for your site. Start by creating a free developer account for Contentful and create your first space, and then return to the command line.

You’ll need to install the Contentful and dotenv plugins to your site with:

1npm install gatsby-source-contentful dotenv

Then create a new text file in the root directory with the below contents:

1CONTENTFUL_SPACE_ID= (Your Contentful Space ID)
2CONTENTFUL_ACCESS_TOKEN= (Your Content Delivery API - access token)
  • To get your Contentful Space ID, login to and select Settings > General Settings

  • To get your Contentful Access Token, login to and select Settings > API keys. Under content delivery/preview tokens, open Example Key 1 (or add a new token). Copy the field under Content Delivery API - access token.

Once you’ve added your Space ID and Access Token to the text file, save it as .env in the main folder of your project.

Then open up gatsby-config.js and paste the following at the top of the file.


Still in gatsby-config.js, find the line containing:

1plugins: [

Paste this directly underneath:

1 {
2 resolve: 'gatsby-source-contentful',
3 options: {
4 spaceId: process.env.CONTENTFUL_SPACE_ID,
5 accessToken: process.env.CONTENTFUL_ACCESS_TOKEN,
6 },
7 },

Directly underneath what you just pasted, you should see the following:

1 {
2 resolve: "@narative/gatsby-theme-novela",
3 options: {
4 contentPosts: "content/posts",
5 contentAuthors: "content/authors",
6 basePath: "/",
7 authorsPage: true,
8 sources: {
9 local: true,
10 // contentful: true,
11 },
12 },
  • To only pull posts from Contentful instead of local files, change local: true to local: false. Otherwise your site will pull content from both local files and Contentful. You can also delete any posts in the local /posts/ directory if you no longer need them.

  • contentful: true is currently “commented out” and prevented from running. Remove the // to enable it.

Once you’re done, save the changes to gatsby-config.js.

The final step before using Contentful is importing the Novela data model into Contentful so that posts are formatted the way Novela expects.

Due to a known issue, you must upload an image to your Contentful media section before the import will work. Log into Contentful and upload an image (any image) under “Media” before proceeding with the next step.

Download the content model, contentful-export.json here by right-clicking the “Raw” button on GitHub and selecting “Save link as…”. Save the JSON file to your site’s main directory on your machine.

Then open up your command line and install the Contentful command line interface with:

1npm install -g contentful-cli

Import contentful-export.json to your own Contentful space with:

1contentful space import --content-file contentful-export.json --space-id YOURSPACEID

The next time you visit your Contentful space, you’ll see two content types: Authors and Posts. Use the add entry option under the Content tab to add new authors or posts:

Different content types for Novela inside Contentful
Different content types for Novela inside Contentful

Finally, use git status to double-check which files are about to be committed, and then push your commit live!

Your Gatsby site now pulls all its content from Contentful. Try adding some new authors and posts inside Contentful and then restarting your Gatsby Cloud preview to check that it’s working.

Hosting your finished site

While Gatsby Cloud is a simple way to view a live online preview of our site and share our work-in-progress with others, you’ll want to find a full-time host for your site before you start publishing publicly.

Two Gatsby-tailored hosts that allow you to start for free are ZEIT and Netlify, both of which will connect to your GitHub repo and generate live builds for you just like Gatsby Cloud. Be sure to check documentation unique to each host, such as saving environment variables (in Netlify and Zeit).

If you don’t have a domain name, you can purchase one directly through your host of choice or from a domain registrar like Namecheap.

What’s next for Novela

There are even more customization options available for Novela, which you can read on Novela’s GitHub page.

Novela is an open-source project, meaning that anyone can contribute code to it. We’re extremely grateful to everyone who’s contributed to making Novela a better Gatsby theme, and we'll continue working to make it a better experience for writers and creators of all kinds.

Follow us on Twitter @narative for updates, and feel free to reach out with questions or suggestions for this guide.

Next time, hit
to go straight to