Updating a Markdown table of contents with a GitHub Action

markdown-toc is a Node script that parses a Markdown file and generates a table of contents for it, based on the headings.

You can run it (without installing anything first thanks to the magic of npx) like so:

npx markdown-toc README.md

This will output the table of contents to standard out.

You can add the following comment to a markdown file:

<!-- toc -->
<!-- tocstop -->

And then run the command like this to update a table of contents in place:

npx markdown-toc -i README.md

I wrote this GitHub Action to apply this command every time the README is updated, then commit the results back to the repository.

Save this as .github/workflows/readme-toc.yml:

name: Update README table of contents

on:
  workflow_dispatch:
  push:
    branches:
    - main
    - master
    paths:
    - README.md

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Check out repo
      uses: actions/checkout@v2
    - name: Update TOC
      run: npx markdown-toc README.md -i
    - name: Commit and push if README changed
      run: |-
        git diff
        git config --global user.email "readme-bot@example.com"
        git config --global user.name "README-bot"
        git diff --quiet || (git add README.md && git commit -m "Updated README")
        git push

You can see this running on the dogsheep/twitter-to-sqlite repository.

Unfortunately these links don't work on READMEs that are rendered by PyPI yet, e.g. twitter-to-sqlite. There's an open issue for that here.

Created 2020-07-22T12:42:38-07:00, updated 2020-07-23T11:05:45-07:00 · History · Edit

Updating a Markdown table of contents with a GitHub Action

Related