This package has been deprecated

Author message:

Use @maiertech/gatsby-plugin-blog.

@mdotasia/gatsby-plugin-blog

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.