Published on

Static site generation with Gatsby 1.0

The popular static site generator Gatsby had its first major release this past July. The framework has quickly gained popularity over the past few months, and for good reason. It offers a lot of cool features right out of the box, along with a rich plugin ecosystem and detailed documentation. I've spent the last few weekends playing around with the framework, and migrating this blog over to the 1.0 release. In this post, I'll highlight six of my favorite Gatsby plugins, and how I've used on this site.

Posts in Markdown (gatsby-transformer-remark)

All of the posts for this site are written in Markdown. It's a lightweight markup language developed for easy conversion to HTML. It looks like this:

## Posts in Markdown (gatsby-transformer-remark)

All of the posts for this site are written in [Markdown][2].

It's a lightweight markup language developed for easy conversion to HTML.

It looks like this:

...

[2]: https://daringfireball.net/projects/markdown/syntax

In Gatsby, this conversion is handled by gatsby-transformer-remark. It takes markdown nodes produced by gatsby-source-filesystem and transforms them into valid HTML. Additionally, Graphql makes it easy to query against frontmatter fields in your posts. Adding tags to posts and having drafts is easily configured. Here's a snippet from my own gatsby-node.js, which illustrates fetching all Markdown posts which are NOT labelled as drafts:

graphql(
  `
    {
      allMarkdownRemark(limit: 1000, filter: { frontmatter: { draft: { ne: true } } }) {
        edges {
          node {
            fields {
              slug
            }
            frontmatter {
              tags
            }
          }
        }
      }
    }
  `
)

The ability to filter on frontmatter gives users fine-grained control over data presentation. Adding a "post type" frontmatter field could allow you to dynamically choose layouts during page creation. Similarly, adding "author" and "path-to-author-avatar" fields could enable dynamic fetching of a specific author biography and corresponding avatar for each post.

Code Highlighting (gatsby-remark-prismjs)

For any bloggers who frequently include code snippets in their posts, gatsby-remark-prismjs is a simple way to enable syntax highlighting. All you have to do is require a prism theme on the layout files used within your site:

require(`prismjs/themes/prism-solarizedlight.css`)

Prism offers lots of different themes, too.

Line highlighting is easy to achieve with the addition of a gatsby-highlight-code-line CSS class and including it on your layout.

Regular line
Regular line
Important line!
Important line!
Regular line
...

Adding Images (gatsby-remark-images)

Gatsby-remark-images allows you to directly include images within your Markdown posts. If you want even more control over images on your site, consider using the gatsby-transformer-sharp, a nice wrapper around the Sharp image processing library.

Adding other file types (gatsby-remark-copy-linked-files)

What if I use a lot of .gif or .pdf files within my posts? Gatsby-remark-copy-linked-files will make your dreams come true. I mean, it will make your GIFs and PDFs work when referenced in your posts. Like this one.

Google Analytics (gatsby-plugin-google-analytics)

I like to keep close tabs on the five or so people who frequent this site, and for that I use Google Analytics. How do I enable this? Yep, you guessed it, another plugin: gatsby-plugin-google-analytics. It's as easy as installing the modules and adding this line to your gatsby-config.js:

    {
      resolve: `gatsby-plugin-google-analytics`,
      options: {
        trackingId: 'Your-Tracking-Id',
      },
    },

Boom! Analytics.

Typography Module (gatsby-plugin-typography)

I like reading. I especially like reading things written in a nice font. Which is why I was happy to find plugin support for Typography.js, another one of Kyle Mathews' projects. Usage of the gatsby-plugin-typography is explained nicely in part two of the Gatsby tutorial. I use st-annes theme for this site.

Bonus: Simple Deployment (gh-pages)

There are a variety of ways to deploy a static site. I've written about Surge before, and Gatsby provides information on how to deploy with Github Pages and Amazon's Cloudfront CDN. I've used Github Pages for the last few years, which is easier than ever with the gh-pages npm module.

For current students: consider applying for the Github Student Developer Pack -- it's free! And it offers a free one-year registration of a .me domain name through Namecheap. You can also purchase a .com or .io domain through their platform for around 10−10-20, depending on the name chosen. Once you have a domain name registered, and have the gh-pages module included as a devDependency, you can add a deploy script to your package.json like this:

{
  ...
  "scripts": {
    "develop": "gatsby develop",
    "build": "gatsby build",
    "serve": "gatsby serve",
    "deploy": "gatsby build --prefix-paths && echo your_domain_name.com > public/CNAME && gh-pages -d public --branch master"
  },
  ...
}

The first command is the Gatsby production build command using a path prefix (mine is just the root path '/', since my site is hosted at e-nichols.github.io). The second command sets up a CNAME record for your custom domain name. CNAME records basically act as an alias for another domain name. Github provides documentation covering how to set this up. This command simply creates a CNAME file within the freshly-created public folder from the first command, containing your_domain_name.com. The third and final command invokes the gh-pages module which handles pushing the content of the public folder to the master branch.

This site

This site is a fork of the Gatsby Remark example website, with some small tweaks to the layouts and fonts used. It's simple and I like it. The source code is available here.

Wrap Up

In an otherwise crowded arena of static site generators, Gatsby stands out as a great resource for React-fans. It's easy to learn, offers a plethora of plugins for customizing posts and pages, and is well-documented (Thank you Kyle and Gatsby contributors!). I'm excited to see how the framework and community around it grow.