This simple script will scan a markdown file for headers and build a table-of-contents, like this:
Before running the first time, put the following on a line by itself (with no leading whitespace):
<!-- TOC FOLLOWS -->
Then run the script like this:
md-toc README.md
md-toc
will collect all h1
, h2
... tags (in markdown: #
, ##
, ...), build nested lists of these, and insert them after the TOC FOLLOWS
line. The header levels used can be customised.
By default, it will only include levels 2 through 4, but you can customise this with another argument:
md-toc README.md 1-5
Each time you run md-toc
, it will again search for the TOC FOLLOWS
line, and delete everything between the START OF TOC
and END OF TOC
comment lines, re-render the new ToC, and insert it.
md-toc
will warn you in the following cases:
- Duplicate headers
- Broken internal links (ie
[click here](#no-such-header)
)
Doug Hoyte, 2023
MIT License