md2toc - generate a table of contents from a Markdown file
$ md2toc [options] some-document.md
Reads the Markdown document specified on the command-line, or standard input if no filename is specified, and writes out a table of contents for that document. The table is itself in Markdown, and is suitable to be embedded in the original file.
The following options are available:
- -l n
-
The lowest number of heading that is included in the table of contents is the specified n: i.e. headings of level n, n+1, n+2 etc. are included. Note that low-numbered headings are more significant than higher-numbered headings.
Defaults to 2, since usually the sole top-level heading in a Markdown document is the title.
- -h n
-
The highest number of heading that is included in the table of contents is the specified n. Defaults to 99 (i.e. in effect, infinity).
- -s n
-
Skip the first n headings, omitting them from the table of contents. Defaults to 0. This is useful when dealing with a Markdown document in which the document title is specified using the same level heading as the section headings;
-s 1will omit the document title from the table. - -q
-
Generated intra-document link fragments substitute hyphens (
-) for question marks (?). I don't remember why this was ever needed. - -a
-
Automatic mode. This is complicated to explain but simple to use. When running in this mode,
md2tocscans its input for the first HTML comment line, i.e. a line of the form<!-- SOMETHING -->with only whitespace before or after it. It then emits a copy of that line followed by the output from running the SOMETHING as a command.
The result is that if a file called
foo.mdcontains a line<!-- md2toc -l 1 -s 1 foo.md -->followed by a generated table of contents, then running the region consisting of the comment line and and the old table through
md2toc -awill result in that region being replaced by a regenerated table of contents.
Mike Taylor, <mike@indexdata.com>
Copyright (C) 2020 by Index Data.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.18.2 or, at your option, any later version of Perl 5 you may have available.