git-md-toc - generate the table of content from the Markdown file(s)
git-md-toc [OPTIONS] [FILE...]
Read an input and generate the table of content (TOC) based on the markup of the file which is assumed Markdown formatted. The outcome is also formatted as Markdown.
The following HTML comments are recognized in a special way and handled as the markers to insert new TOC or update existing one.
-
<!-- toc -->is used to point the place in the document for putting a new TOC.
-
<!-- toc-begin -->,<!-- toc-end -->are used to point the beginning and end of the existing TOC.
Be noticed that these markers themselves must be sticky to the left edge of the lines where they are situated. This rule doesn't spread on the content within.
The updated TOC is always ended with double new line to separate from the further text below. On the same reason, if the TOC is preceded with some text above, the double new line is prepending the TOC.
Early, before 2022, another set of markers was used: md-toc,
md-toc-begin and md-toc-end.
Currently they are considered obsolete and not recommended in use. However they are still supported but replaced with the newer ones when TOC is updated.
Be noticed that you shouldn't mix old and new paired markers to designate the beginning and end of the same TOC.
-
-h, --help
Print this help and exit.
-
-t TITLE, --title=TITLE
Specify the title for the TOC. If
TITLEis not specified or it's empty value, the default valueTable of Contentis assumed. -
-l LEVEL, --level=LEVEL
Set the header level used for the TOC title. Available values are
1to6. The default value is1. -
-d DEPTH, --depth=DEPTH
Use
DEPTHto control how many levels of headers to include in the TOC. Available values are1to6. Defaults to6. -
-T TEXT_ENCODE,TITLE_ENCODE, --transcode=TEXT_ENCODE,TITLE_ENCODE
Point encodings for the file content or the TOC title. It should be specified explicitly to correctly parse inputs in UTF-8 or other encodings.
The first value tells that both text and TOC title come in the particular encoding.
The second value specifies encoding for the TOC title only. It can be useful in DOS sessions for setting another encoding for the TOC title declared in the command line. For example, to correctly set the TOC title in Cyrillic in UTF8 encoded files I had to separately declare
cp1251for the TOC title encoding. -
--title-transcode=TITLE_ENCODE
Point another encoding for the TOC title. It works similarly as
--transcode=,TITLE_ENCODE(note the comma in the option).This option is obsolete and kept for compatibility reasons. Use -T/--transcode instead.
-
-u, --update
Update the file with the new table of content. It works even when reading from STDIN. In this case the outcome will be printed to STDOUT.
-
-c, --create-before
-
-C, --create-after
Create and add the TOCs before and/or after the input.
In combination with the -u/--update option they allow to create and insert the TOCs from the scratch even if no any TOC marker is specified.
-
--folding=collapse|expand
Make TOC foldable. Two values
collapseandexpandare enabled.If specified, the -t/--title option is implied.
When the document has many sections and TOC becomes correspondingly quite big, it can be more friendly to make TOC foldable.
- https://metacpan.org/pod/Text::Markdown
- https://metacpan.org/pod/Text::MultiMarkdown
- https://metacpan.org/pod/Markdown::TOC
- https://github.com/ekalinin/github-markdown-toc
- https://github.com/ekalinin/github-markdown-toc.go
- https://github.com/frnmst/md-toc
- https://github.com/eGavr/toc-md
- https://github.com/jonschlinkert/markdown-toc
Ildar Shaimordanov <ildar.shaimordanov@gmail.com>
Copyright (c) 2019-2022 Ildar Shaimordanov. All rights reserved.
MIT License