gatsby-plugin-changelog-context

Automate adding a changelog of commit history to your Gatsby -generated pages.

Each page’s commit history is added to your page templates via the page context. This then gives you the ability to display/consume this data within your page template however you like.

• Perquisites
• Install
  • Add Dependency
  • Add Plugin to GatsbyJS Site
  • Adding Filesystem Data to your Page Query
  • Options
    • Example
• Usage
• Credit

Perquisites

This Gatsby plugin requires the location of each page with respect to the filesystem, as stored in git; This is to ensure we get the correct/relevant commit history for the page from git.

This fits with a common workflow in a typical Gatsby setup, when programmatically generating pages. How to add this data is provided in more detail below.

Install

Add Dependency

Install using yarn/npm

npm install --save gatsby-plugin-changelog-context
# or
yarn add gatsby-plugin-changelog-context

and add the plugin to your config file:

Add Plugin to GatsbyJS Site

// gatsby-config.js
module.exports = {
  ...
  plugins: [
    'gatsby-plugin-changelog-context',
  ]
};

Adding Filesystem Data to your Page Query

To ensure you get only commits for each page, separately, you need to ensure that your pages include the absolute path to the file containing the content, e.g. the Markdown file. You can do this by including the edges.node.fileAbsolutePath parameter in your GraphQL query.

For example, when programmatically generating pages from Markdown files, you can modify your createPages node API call to add the required data:

const { data, errors } = await graphql(`
  {
    allMarkdownRemark(sort: { fields: [frontmatter___date], order: DESC }) {
      edges {
        node {
          fileAbsolutePath
          fields {
            slug
          }
          frontmatter {
            title
          }
        }
      }
    }
  }
`);

// ...

const blogPostTemplate = path.resolve('./src/templates/blog-post.js');

data.allMarkdownRemark.edges.forEach(post => {
  createPage({
    path: post.node.fields.slug,
    component: blogPostTemplate,
    context: {
      slug: post.node.fields.slug,
      // required for [gatsby-plugin-changelog-context]
      fileAbsolutePath: post.node.fileAbsolutePath,
    },
  });
});

Options

The following options are supported:

Example

As an example, to configure the commit date format to be a unix timestamp (the default is ISO8601):

// gatsby-config.js
module.exports = {
  ...
  plugins: [
    {
      resolve: 'gatsby-plugin-changelog-context',
      options: {
        git: {
          '--date': 'unix',
        },
      },
    },
  ]
};

Usage

The commit history for each page is accessed from the page template’s pageContext. In the above example, which uses a page template, called blogPostTemplate, we can access the commit history via the props.pageContext.changelog:

const BlogPostTemplate = ({ data, pageContext }) => {
  // ...

  <section>
    <h4>Changelog</h4>

    {pageContext.changelog.map(({ hash, date, message }) => (
      <p key={hash}>
        {moment(date).format('ddd Do MMM, YYYY')} - {message}
      </p>
    ))}
  </section>;

  // ...
};

The changelog pageContext prop has the following type signature:

const changelog: Commit[]; // Empty array, or array of Commit objects

// Commit object
interface Commit {
  hash: string; // commit hash
  data: string; // ISO datetime
  message: string; // commit summary
  body: string; // commit body
  author_name: string;
  author_email: string;
  refs: string;
}

Credit

This plugin was inspired by a tweet from Søren Birkemeyer:

I have added changelogs to my blog! 📋😎

Whenever I go back to a blog post to update or fix something, the commit message(s) are now automatically appended at the bottom of the page.

Here's how I did this with @eleven_ty:

👉 https://t.co/ObMC4waYKq#keepachangelog

— Søren Birkemeyer (@polarbirke) September 4, 2019