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:

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

1
<!-- toc -->
2
<!-- tocstop -->

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

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

1
name: Update README table of contents
2

3
on:
4
  workflow_dispatch:
5
  push:
6
    branches:
7
    - main
8
    - master
9
    paths:
10
    - README.md
11

12
jobs:
13
  build:
14
    runs-on: ubuntu-latest
15
    steps:
16
    - name: Check out repo
17
      uses: actions/checkout@v2
18
    - name: Update TOC
19
      run: npx markdown-toc README.md -i
20
    - name: Commit and push if README changed
21
      run: |-
22
        git diff
23
        git config --global user.email "readme-bot@example.com"
24
        git config --global user.name "README-bot"
25
        git diff --quiet || (git add README.md && git commit -m "Updated README")
26
        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.