Worse is Better: Setting up Gatsbyjs drafts

Worse is Better is a development philosophy that prioritizes practicality over functionality.

TLDR setup a drafts folder and conditionally include it based on development status

Git Drafts Workflow

Initially this site maintained gatsby drafts using a feature branch workflow, creating a new branch for each article and merging it when done. This resulted in many git commands being executed when adjusting styling, fixing typos, and comparing article formatting with newly implemented features from master

This was convenient because it didn't involve any custom code, but required too much context switching for a single author environment.

Drafts as Metadata

Gatsbyjs allows custom metadata in articles, commonly called frontmatter. An obvious way to implement drafts is to add a draft: true|false key to the frontmatter and rewrite it whenever an article is finished.

---
draft: true

path: "/blog/gatsby-drafts"
parent: "/blog"
title: "Worse is Better: Setting up Gatsbyjs drafts"
date: 2019-11-18
tags:
  - software
  - philosophy
---

[Worse is Better](https://en.wikipedia.org/wiki/Worse_is_better) is a development philosophy...

this articles frontmatter

Downsides

With drafts as article metadata it is possible to for that state to get lost. The author can't easily answer the questions how many drafts are on the site, what remains to be published. In addition every place articles are fetched drafts must be filtered. It would be easy to accidentally omit an article

Drafts as Organization

Chase Adams proposed an alternative: Why not organize drafts on the filesystem? On this sites configuration each article chooses its own path regardless of filesystem position. By adding a drafts folder and conditionally including that folder in gatsby it becomes impossible to accidentally publish content

Config

gatsby-config.js

const includeDrafts = process.env.NODE_ENV !== "production"

module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `markdown-pages`,
        path: path.join(__dirname, "content"),
      },
    },
    includeDrafts
      ? {
          resolve: `gatsby-source-filesystem`,
          options: {
            name: `markdown-drafts`,
            path: path.join(__dirname, "drafts"),
          },
        }
      : undefined,
    `gatsby-transformer-remark`,
    ...
  ].filter(plugin => !!plugin),
}

Code explination: When gatsby is run with npm run develop NODE_ENV is development and the source plugin includes the drafts directory. When run with npm run build NODE_ENV is production and the plugin is replaced with undefined, which is filtered out of the array