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
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 "firstname.lastname@example.org" 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