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-sitecd my-siteyarn init -yyarn 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.jsmodule.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 /
.
# TestMy 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 }) => (<div><h1>My Site!</h1>{children}</div>);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 }) => (<Layout>{element}</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.
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