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.
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.
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
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
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
and a css file at
src/components/layout.css. I chose to
add a system font stack to mine.
We'll also create two new files:
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
wrapRootElement that we can use to wrap the entire
site in our layout.
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.
You can check out the site we built in this post at https://github.com/ChristopherBiscardi/basic-gatsby-site-example