Markdown Meta Action
Tags: github, githubactions
Published: 2021-05-10 08:59:14

---
title: Markdown Meta Action
published: true
date: 2021-05-07 18:01:58 UTC
tags: github, githubactions
canonical_url: https://michaelheap.com/markdown-meta-action/
series: Action Spotlight
---

| Fact Sheet | |
| --- | --- |
| Author | mheap |
| Contributors | 1 |
| Stars | 0 |
| Repo | [https://github.com/mheap/markdown-meta-action](https://github.com/mheap/markdown-meta-action) |
| Marketplace | [https://github.com/marketplace/actions/markdown-meta](https://github.com/marketplace/actions/markdown-meta) |

## What does it do?

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

`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: "Action Spotlight"
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](https://github.com/mheap/markdown-meta-action/blob/3484e15d3b1ee6d1baec025e7a3167e728aea7b6/index.js#L7-L8)
- Next, it uses the `gray-matter` library to [extract the frontmatter](https://github.com/mheap/markdown-meta-action/blob/3484e15d3b1ee6d1baec025e7a3167e728aea7b6/index.js#L9)
- [Then for each value in the frontmatter, it sets an output](https://github.com/mheap/markdown-meta-action/blob/3484e15d3b1ee6d1baec025e7a3167e728aea7b6/index.js#L10-L12). 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 }}
```