70 %

Toast is in Beta!Learn more →

Chris Biscardi

Building a Basic Gatsby Site

Gatsby is a fantastic tool for building out almost any site you can think of. Due to how flexible it is, some people find themselves looking for a way to "just write markdown" and get a website.

So lets initialize a new project and install a couple dependencies. Only gatsby, react, and react-dom are strictly necessary for a gatsby site to run. To add markdown support we'll use gatsby-mdx so that we don't have to write any GraphQL to build new pages.

mkdir my-site
cd my-site
yarn init -y
yarn add gatsby react react-dom gatsby-mdx @mdx-js/mdx @mdx-js/tag

Now that we've installed the necessary dependencies, we need to create a gatsby-config.js file. This is the core of our gatsby site if we want to do more custom work and it will be very small for this project.

// gatsby-config.js
module.exports = {
plugins: ["gatsby-mdx"]

If we run yarn gatsby develop now, we'll see our gatsby site running without any pages at all, so lets fix that. Create a new file at src/pages/index.mdx. This will turn into our home page at /.

# Test
My index page

Any JavaScript file or MDX file in src/pages will turn into a page at the relative path. So a new file at src/pages/about.mdx will create a new page at /about.

That's it, run yarn gatsby develop and you can start creating new pages.


This is actually too little for a lot of people. It has no navigation, layout, etc. To add a layout, we can create a file at src/components/layout.js.

import React from "react";
import "./layout.css";
const SiteLayout = ({ children, ...props }) => (
<h1>My Site!</h1>
export default SiteLayout;

and a css file at src/components/layout.css. I chose to add a system font stack to mine.

body {
font-family: -apple-system, BlinkMacSystemFont,
"Segoe UI", Roboto, Helvetica, Arial, sans-serif,
"Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";

We'll also create two new files: gatsby-ssr.js and gatsby-browser.js. Both files will include the exact same content: we'll import our layout, our css, and React (because we're using JSX syntax). Gatsby offers us an API called wrapRootElement that we can use to wrap the entire site in our layout.

import React from "react";
import "./src/components/layout.css";
import Layout from "./src/components/layout";
export const wrapRootElement = ({ element }) => (


Now in our layout we can include any navigation, layout elements like sidebars, or anything else we want. We've taken a bare bones approach so that we could focus on what we wanted to build. From here, we can make our site as custom or as bare bones as we want. We can explore learning React or GraphQL, experiment with css-in-js, or find out what's possible in the Gatsby tutorial. We can also choose to keep everything in a single CSS file and a single Layout file while writing Markdown in src/pages.

If you end up with something that you like and want to re-use, you can make a gatsby starter, or even a theme.

You can check out the site we built in this post at https://github.com/ChristopherBiscardi/basic-gatsby-site-example