Sometimes all we need is a static site without all the hassles of building and configuring servers. It could be a blog, an ad campaign, a listing for an event or something simple. We require a static site generator to generate build files and render these files as is, upon request. In this article, we will be building a static site using Gatsby.js.
Imagine going to a grocery store, all you want is on the shelf and ready to be sold. You can buy as much as you want, pay and leave. Whereas there are stores where you can buy groceries as seen on the shelf, but some items are not in the store, but in the warehouse and whenever you want to buy it, you make a request through the storekeeper who gets it for you.
These analogies represent a static site and a dynamic site respectively. Where in a static site, it’s basically WYSIWYG, but in a dynamic site there are servers which handle requests and respond with data on request. Static sites give us the benefit of speed and simplicity.
There is a host of static site generators but for this article, we will be building a static blog with Gatsby. Gatsby is a fast and robust static site generator for React. Talking about being robust, Gatsby renders dynamic content using React components into static HTML content. You will learn how to build a simple static blog using Gatsby. The blog would be able to take markdown files and render them on page load. GraphQL will be used to query our files.
Knowledge of HTML, CSS, JavaScript, and React is required. Knowledge of GraphQL is not compulsory but is of added advantage. For this project, you need Node and NPM installed. Installing Node comes with the latest version of node package manager (npm).
Gatsby is installed in what is called starters, these are preset builds for specific purposes and make development easy. For this project, we shall be using the Gatsby default starter which is the starter for a blog. There are lots of starters and they can be found here. First, we install Gatsby CLI tool globally via npm with:
https://gist.github.com/2decd248d0871b2b2b01c5b746d38172
Gatsby CLI enables us to build apps faster and comes with a development server and a hot reload function, therefore, changes made to our source files are immediately visible in our browser. We install the Gatsby default starter with:
https://gist.github.com/bbf8d9101377772e5bc6a440adba1f18
This creates our Gatsby files in the project folder gatsby-blog and changes the directory to that folder. To run our development server, in the console run:
https://gist.github.com/6835189aa38f5558b38719d5e859e397
The development server is hosted on localhost:8000
This is simply a development server. To start a production build, run the build command:
https://gist.github.com/9ea390f005ab01cb0bef1a0045655d03
Gatsby, like some other static site generators, employ the use of plugins to include functionalities in our blog. These plugins either extend the functionality of Gatsby (Functional plugins), create nodes for our source files to be queried by GraphQL (Source Plugins) or transform files from various formats such as markdown which is not usable by Gatsby to a form which is usable (Transformer plugin).
In addition to the default plugins installed by the starter, install:
- gatsby-source-filesystem: This is a source plugin we use in creating nodes for our source files.
- gatsby-plugin-typography: Using libraries such as bootstrap in Gatsby come with little more complexities and is difficult to customize, so we use a library Typography.js. Typography lets us generate typographic CSS. It also comes with awesome themes of which bootstrap is one of them.
- typography-theme-bootstrap: This is the custom bootstrap theme for typography. We would employ this to enable basic bootstrap styling.
- gatsby-transformer-remark: Transformer plugin to transform our markdown files.
Install these plugins with:
https://gist.github.com/1f152af065dce7b98e9311937dde5469
Now we have all our dependencies saved. Let’s get to crafting our blog.
Gatsby lets us create a layout for our blog, this helps us place elements of our blog which we would like to be consistent across all the pages of the blog such as header, navigation bars, and footers. In this blog we would require just a header to be consistent across all the pages and styling would be done inline with the inline style props.
So far our blog has two pages and an error 404 page, you can see the pages in the directory /src/pages/, remove the page-2.js file in src/pages/, we won’t be needing it. In src/layout/index.css/, wipe all the CSS styling in place, we wouldn’t be needing all of that for this.
In /src/layouts/index.js, note the imported components and packages.
Link is used in place of anchor tag and uses the ‘to” property to define a destination for the link.
Edit the blog title, as well as the background color of the header:
https://gist.github.com/7b082bd2f4d74a28a1d320f06caeb26e
Now we have our layout all set. Let’s enable our typography bootstrap theme. First, create a file typography.js in a new folder src/utils/. In typography.js, edit the file to:
https://gist.github.com/6e6969e62c4aa4a1f45b2aba7a61a648
This creates a typography module to be exported. Where do we export the module to so it is accessible globally on our project? In our root directory, there is a file named gatsby-config.js. This is where we configure all plugins and other site configurations. In gatsby-config.js, we specify our typography plugin and file path, let’s also specify our gatsby-source-filesystem and gatsby-transformer-remark plugins at once:
https://gist.github.com/2ae6286f057e78cc7f3df1ffdb173e48
Note:
gatsby-react-helmetplugin enables the modification of head tags in our blog.
So far we have been decorating our blog a bit. Our blog is to be built in a way, content will be written in markdown and this content will be transformed and passed into our React component to be rendered. Create a folder /src/blog-posts/ this would house our blog posts in markdown. Let’s create sample blogs posts in markdown.
/src/blog-posts/ecosystem.md https://gist.github.com/7f601d755890524ceda611110ac5c5a7
and
/src/blog-posts/post2.md https://gist.github.com/c1d69c8fc2513629e0d4f3b349c97afb
Note the data between both triple dashes (---), this is known as frontmatter and would be used to collect blog specific data which we would like to be displayed on our page. Now we have our blog posts but so far, we can’t see them on our page, not to worry, we are getting to that next.
React makes use of GraphQL amongst others to fetch data into our react components. GraphQL is a query language. We will be employing this powerful tool to query our blog-posts into our react components. Restart your development server with:
https://gist.github.com/ea50c99f539be0acce2afa16352784aa
This affects all the changes and plugins added to the gatsby-config.js file.
A GraphQL IDE called GraphiQL can be used to view our queries and data before we pass them to our React components. GraphiQL can be accessed when our development server is running on http://localhost:8000/___graphql
Since we have the gatsby-source-filesystem and gatsby-transformer-remark plugin installed and configured in gatsby-config.js, we can query all markdown files in our project folder. Let’s display all our blog posts on the home screen. Edit index.js in src/pages to:
src/pages/index.js https://gist.github.com/2364696199d0fa57dfe21ba75301c55c
Here we passed in data fetched by GraphQL to our react component, our query? Include this at the bottom of the script:
https://gist.github.com/6cd80356c8fe9f7c63e819bda4bebd5c
This is our query and as we can see we fetched data from the “allMarkdownRemark” node. You can run this query starting from the allMarkDownRemark node to better see how data is fetched and displayed as an object.
Now we have our blog posts displayed on our home screen.
Notice that the blog posts are not sorted according to their dates, GraphQL gives us the ability to sort and filter nodes in our queries. In src/pages/index.js edit the allMarkdownRemark query to:
https://gist.github.com/7ea48923b4638777263c6dccb4d33caa
Our blog posts are sorted in descending order.
So far we have created a blog front, but what about our articles and posts, they don’t just remain on the front with just excerpts, we need to see the whole content on a different page. We shall do this programmatically so new pages are generated per post. To generate pages with Gatsby we need to:
- Create the ‘path’ or ‘slug’ for the page
- Create the ‘page’
We will use two Gatsby APIs to accomplish this, they are onCreateNode and createPages API. All we need do is simply export a function with the name of the API from ‘gatsby-node.js’. In the root directory, we create the file gatsby-node.js. Edit it to:
https://gist.github.com/2d8ccec573564b9b1ae4779ca6934d0f
To create slugs of our markdown files on the MarkdownRemark node, we use the createFilePath function that ships with the gatsby-source-filesystem. This function finds the parent File node of our files as they contain details of our files and it creates the slugs. We use the createNodeField function on our onCreateNode API to add our new slugs to the MarkdownRemark node so the slugs can be queried in our components. The if statement is first used to verify if the node type is a MarkdownRemark before creating the slug. To view the slugs for our files you can query it in GraphiQL with:
https://gist.github.com/c7e35ece60df98263ca283cf4cf5b3f3
Before we create the blog pages, let’s create a template for our blog pages. We create a file blog-post.js in a new directory src/templates/. Create the react React component like:
https://gist.github.com/20beb2bb15990afc853039bafeddb897
Add the GraphQL query at the bottom with:
https://gist.github.com/02946bc155aa26c0907ebaa2a9aee203
Now we have a template for our pages let’s create our pages with the createPages API. In the gatsby-node.js file this is included:
https://gist.github.com/0e9ddb4a365199440f406c331865691a
Above, we called the createPages API which creates the pages from the slugs we created earlier, also we specified the GraphQL queries to fetch the required data in a promise statement as well as specify the path to the blog template we created earlier. Restart the development server and we have our pages created. We can’t see it now unless you type in the file path in the URL bar.
Lastly, we set a link to each of our blog posts from our home page.
In src/pages/index.js, each blog section is masked with a <Link> element and the to prop is set to the slug of the blog.
https://gist.github.com/72d92e1872723d9e6536da69552d6a4e
Also, we include the slug query in our GraphQL queries at the bottom:
https://gist.github.com/30e2cf6c35fbf063d35714aad8f289b5
We restart our development server, and when you click on any of the blog posts you get to the main article page, fast.
In this article we have built a static blog using Gatsby and also we have seen we can fetch data seamlessly using GraphQL. Gatsby allows us to utilize data from multiple sources including but not limited markdown, CSV and CMS like Drupal and Wordpress. Feel free to style your blog anyway and there are lots of styling options available, you can find them here. Also, you can work with utilizing data other aforementioned data types. Check out the source code here.