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.

Related

• github-actions GitHub Actions job summaries - 2022-05-17
• github-actions Commit a file if it changed - 2020-04-19
• markdown Converting HTML and rich-text to Markdown - 2020-05-09
• readthedocs Updating stable docs in ReadTheDocs without pushing a release - 2023-08-20
• homebrew Automatically maintaining Homebrew formulas using GitHub Actions - 2023-06-21
• mastodon Building Mastodon bots with GitHub Actions and toot - 2023-02-02
• github-actions Using Prettier to check JavaScript code style in GitHub Actions - 2020-12-31
• github-actions Conditionally running a second job in a GitHub Actions workflow - 2022-07-11
• python Using cog to update --help in a Markdown README file - 2021-11-18
• github-actions Open a debugging shell in GitHub Actions with tmate - 2020-09-14

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