NAME

md2toc - generate a table of contents from a Markdown file

SYNOPSIS

$ md2toc [options] some-document.md

DESCRIPTION

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 1 will 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, md2toc scans 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.md contains 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 -a will result in that region being replaced by a regenerated table of contents.

AUTHOR

Mike Taylor, <mike@indexdata.com>

COPYRIGHT AND LICENSE

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.