npm package: @mdotasia/gatsby-plugin-blog
Description: 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
Author: Thilo Maier
Latest version: 0.7.0
Deprecated: Use @maiertech/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

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

just like in [Jekyll](https://jekyllrb.com/). A blog post's frontmatter must contain a `title` property.

## Installation

```bash
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`](https://www.gatsbyjs.org/packages/gatsby-source-filesystem/), define a filesystem source for the parent directory in the `plugins` array in your `gatsby-config.js`:

```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:

```js
{
  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](https://github.com/jxson/front-matter), which uses package [js-yaml](https://github.com/nodeca/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](http://yaml.org/type/timestamp.html) must conform to [ISO 8601](https://en.wikipedia.org/wiki/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`](https://www.gatsbyjs.org/docs/querying-with-graphql/#formatting-dates) for formatting dates in GraphQl queries. However, `formatString` converts the timestamp to UTC and then formats it nicely (see [here](https://github.com/gatsbyjs/gatsby/blob/82d9188aba871bb0bb94e32c3e590cb13ae3cd12/packages/gatsby/src/schema/types/type-date.js#L102)).

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.