An utility that is able to generate a table of contents for a markdown file.
Project description
Automatically generate a compliant 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.
Rules for generating the table of contents are determined by the selected markdown parser. md_toc aimes to be as conformant as possible in respect to each one of them.
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 and builds a correct output.
Conventions
PEP.
4 space indentation.
Helps
usage: md_toc [-h] [-i] [-n] [-t TOC_MARKER] [-v] {github,cmark,redcarpet,gitlab} ... FILE_NAME Markdown Table Of Contents: Automatically generate a compliant table of contents for a markdown file to improve document readability. 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 the corresponding content -t TOC_MARKER, --toc-marker TOC_MARKER set the string to be used as the marker for positioning the table of contents. Defaults to [](TOC) -v, --version show program's version number and exit markdown parser: {github,cmark,redcarpet,gitlab} Return values: 0 OK, 1 Error, 2 Invalid command Copyright (C) 2018 Franco Masotti, frnmst License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.
usage: md_toc github [-h] [-u [{-,+,*}] | -o [{.,)}]] [-l [{1,2,3,4,5,6}]] Use Commonmark rules to generate an output. If no option is selected, the default output will be an unordered list with the respective default values as listed below optional arguments: -h, --help show this help message and exit -u [{-,+,*}], --unordered-list-marker [{-,+,*}] set the marker and enables unordered list. Defaults to - -o [{.,)}], --ordered-list-marker [{.,)}] set the marker and enables ordered lists. Defaults to . -l [{1,2,3,4,5,6}], --header-levels [{1,2,3,4,5,6}] set the maximum level of headers to be considered as part of the TOC. Defaults to 3
usage: md_toc redcarpet [-h] [-u [{-,+,*}] | -o [{.}]] [-l [{1,2,3,4,5,6}]] Use Redcarpet rules to generate an output. If no option is selected, the default output will be an unordered list with the respective default values as listed below. Gitlab rules are the same as Redcarpet except that conflicts are avoided with duplicate headers. optional arguments: -h, --help show this help message and exit -u [{-,+,*}], --unordered-list-marker [{-,+,*}] set the marker and enables unordered list. Defaults to - -o [{.}], --ordered-list-marker [{.}] set the marker and enables ordered lists. Defaults to . -l [{1,2,3,4,5,6}], --header-levels [{1,2,3,4,5,6}] set the maximum level of headers to be considered as part of the TOC. Defaults to 3
TODO and FIXME
grep -e TODO -e FIXME -n */*.py
License
Copyright (C) 2017-2018 frnmst (Franco Masotti) <franco.masotti@live.com> <franco.masotti@student.unife.it>
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/>.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.