Markdown Meta Action

Content containing some YAML frontmatter is very common nowadays (in fact, you're reading a post that uses it right now).

Today's action allows you to use that data in any way that you need in your workflows.

What does it do?

markdown-meta allows you to read that metadata and makes it available as an output in your GitHub Actions workflow.

The frontmatter for this file is as follows:

yaml
---
title: Markdown Meta Action
description: Read the frontmatter from your markdown files and use the values in your workflows
slug: markdown-meta-action
date: "2021-05-07T19:01:58+01:00"
category: "Tech"
tags:
 - github-actions
---

Given that file we can run the following workflow that outputs the post title:

yaml
name: Get Post Meta
on: push
jobs:
 post-meta:
 name: Post Meta
 runs-on: ubuntu-latest
 steps:
 - name: Checkout
 uses: actions/checkout@v2
 - name: Markdown Meta
 uses: mheap/markdown-meta-action@v1
 id: meta
 with:
 file: ./_posts/markdown-meta-action.md
 - name: Output the post title
 run: echo "${{ steps.meta.outputs.title }}"

We use the id parameter to name the markdown-meta step meta and then access the data returned by it using steps.meta.outputs. Each key in the frontmatter is available:

• steps.meta.outputs.title
• steps.meta.outputs.description
• steps.meta.outputs.slug
• steps.meta.outputs.date
• steps.meta.outputs.category
• steps.meta.outputs.tags

How does it work?

This is a really tiny action, just 7 lines long:

• It fetches the filename to read from the file input and reads the content into a string
• Next, it uses the gray-matter library to extract the frontmatter
• Then for each value in the frontmatter, it sets an output. The key name is run through slugify to remove special characters and whitespace
  • a key with spaces becomes a-key-with-spaces
  • t!tle becomes ttle
  • 🚀 lift-off becomes lift-off

As it uses core.setOutput() any complex data types such as objects or arrays are JSON encoded before being output. This means that in the above example, tags will be ["github-actions"].

Common use cases

The best use case that I can think of for this action is automated blog post updates:

yaml
name: Get Post Meta
on: push
jobs:
 post-meta:
 name: Post Meta
 runs-on: ubuntu-latest
 steps:
 - name: Checkout
 uses: actions/checkout@v2
 - name: Get latest post
 run: |
 cd _posts
 echo "::set-output name=post_name::$(ls -rt | tail -n 1)"
 id: latest_post
 - name: Markdown Meta
 uses: mheap/markdown-meta-action@v1
 id: meta
 with:
 file: ./_posts/${{ steps.latest_post.outputs.post_name }}
 - uses: ethomson/send-tweet-action@v1
 with:
 status: "I just published! ${{ steps.meta.outputs.title }} https://michaelheap.com/${{ steps.meta.outputs.slug }}"
 consumer-key: ${{ secrets.TWITTER_CONSUMER_API_KEY }}
 consumer-secret: ${{ secrets.TWITTER_CONSUMER_API_SECRET }}
 access-token: ${{ secrets.TWITTER_ACCESS_TOKEN }}
 access-token-secret: ${{ secrets.TWITTER_ACCESS_TOKEN_SECRET }}