md-toc 1.0.0

An utility that is able to generate a table of contents for a markdown file.

Automatically generate a table of contents for a markdown file to improve document readability.

Description

The table of contents generated by this program is designed to work with several markdown parsers such as the one used by GitHub and GitLab.

When used with the in-place option this script will write the table of contents at the first occurrency of a marker. The default marker is [](TOC) which will result as invisible when reading the parsed markdown file.

By default, titles up to three indentation levels (in HTML: h1, h2, h3) will be included in the table of contents.

As a final remark, it is possible to generate an ordered and an unordered table of contents. In both cases, each element of the toc is by default a clickable link to a paragraph in the page. It is also possible to generate non-linked version of the TOC.

Video

Documentation

http://frnmst.github.io/md-toc

Please read carefully the Markdown specification section of the documentation to learn how this program parsers markdown files.

Conventions

• PEP.

• 4 space indentation.

Help

usage: md_toc [-h] [-i] [-n] [-o] [-p {standard,github,redcarpet,gitlab}]
              [-t TOC_MARKER] [-l HEADER_LEVELS] [-v]
              FILE_NAME

Markdown Table Of Contents

positional arguments:
  FILE_NAME             the I/O file name

optional arguments:
  -h, --help            show this help message and exit
  -i, --in-place        overwrite the input file
  -n, --no-links        avoids adding links to corresponding content
  -o, --ordered         write as an ordered list
  -p {standard,github,redcarpet,gitlab}, --parser {standard,github,redcarpet,gitlab}
                        decide what markdown parser will be used to generate
                        the links. Defaults to standard
  -t TOC_MARKER, --toc-marker TOC_MARKER
                        set the string to be used as the marker for
                        positioning the table of contents
  -l HEADER_LEVELS, --header-levels HEADER_LEVELS
                        set the maximum level of headers to be considered as
                        part of the TOC
  -v, --version         show program's version number and exit

Return values: 0 OK, 1 Error, 2 Invalid command

License

Copyright (C) 2017-2018 frnmst (Franco Masotti) <[e-mail]> <[e-mail]>

md-toc is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

md-toc is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with md-toc. If not, see <http://www.gnu.org/licenses/>.