Community Plugin

gatsby-plugin-blog

This plugin adds support for creating a blog in your Gatsby site. Blog posts reside in a directory that can be configured. Each blog post is Markdown file with this naming convention

<YYYY>-<MM>-<DD>-<slug>.md

just like in Jekyll. A blog post’s frontmatter must contain a title property.

Installation

yarn add @mdotasia/gatsby-plugin-blog

Configuration

In your Gatsby project decide the folder in which yuo would like to keep your blog posts, e.g. content/blog. We refer to content as parent directory and to blog as source directory. Using gatsby-source-filesystem, define a filesystem source for the parent directory in the plugins array in your gatsby-config.js:

{
  resolve: "gatsby-source-filesystem",
  options: {
    name: "content",
    path: `${__dirname}/content/`
  }
}

Then add @mdotasia/gatsby-plugin-blog to plugins. This snippet shows the minimal configuration:

{
  resolve: "@mdotasia/gatsby-plugin-blog",
  options: {
    template: `${__dirname}/src/templates/post.jsx`
  }
}

You can use the following options:

Option	Default	Description
`dateFormat`	`MMM D, YYYY`	Format dates in `prev` and `next` objects.
`pathPrefix`	`""`	Blog posts are mapped to `/<YYYY>/<MM>/<DD>/<slug>` by default. If `pathPrefix` is set, they are mapped to `/<pathPrefix>/<YYYY>/<MM>/<DD>/<slug>`. Can be different from `sourceDir`.
`sourceDir`	`blog`	By default blog posts reside in source directory `blog`, a subdirectory in one of your filesystem sources. Can be different from `pathPrefix`.
`template`		You need to create your own template for blog posts. Your template receives `path` and a `context` objext with `prev` and `next`, which are objects with `date`, `path` and `title`. The date is is formatted with `dataFormat`.

Time zone pitfalls

In order to parse the frontmatter of Markdown files, Gatsby uses package front-matter, which uses package js-yaml. In order to understand how Gatsby handles a frontmatter date such as 2018-08-03, we need to look at what js-yaml does under the hood. YAML timestamps must conform to ISO 8601 with the exception that if a timestamp does not specify a time zone, it is UTC by convention.

If you select a frontmatter date in a GraphQL query, the timestamp contained in the result comes with a time zone. Either because you specified the time zone explicitly in the frontmatter timestamp or because it is UTC by convention. You could pass the raw timestamp to a template and let the template take care of formatting the timestamp nicely. But this would come with the drawback that you need to load a date formatting library into the browser

Alternatively, Gatsby offers formatString for formatting dates in GraphQl queries. However, formatString converts the timestamp to UTC and then formats it nicely (see here).

A date embedded into a filename such as 2018-08-03-blog-post-slug.md obviously does not specify a time zone. That is way in line with how Gatsby interprets frontmatter dates, this plugin interprets the date embedded into the filename as UTC. At this point you cannot specify a time zone in which enbedded filename dates are interpreted. This could lead to discrepancies between a blog post’s path and the date actually displayed via the blog post template. Once Gatsby implements time zone support, this plugin will follow suit.