Metadata-Version: 2.1
Name: md-toc
Version: 3.0.0
Summary: An utility that is able to generate a table of contents for a markdown file.
Home-page: https://github.com/frnmst/md-toc
Author: Franco Masotti
Author-email: franco.masotti@live.com
License: GPL
Keywords: markdown toc
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Topic :: Utilities
Classifier: Intended Audience :: End Users/Desktop
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3
Requires-Dist: fpyutils (>=0.0.2)

Markdown Table Of Contents
==========================

|pypiver|    |license|    |pyver|    |downloads|

.. |pypiver| image:: https://img.shields.io/pypi/v/md-toc.svg
               :alt: PyPI md-toc version

.. |license| image:: https://img.shields.io/pypi/l/md-toc.svg?color=blue
               :alt: PyPI - License
               :target: https://raw.githubusercontent.com/frnmst/md-toc/master/LICENSE.txt

.. |pyver| image:: https://img.shields.io/pypi/pyversions/md-toc.svg
             :alt: PyPI - Python Version

.. |downloads| image:: https://pepy.tech/badge/md-toc
                 :alt: Downloads
                 :target: https://pepy.tech/project/md-toc

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
-----

.. image:: https://asciinema.org/a/234434.png
     :target: https://asciinema.org/a/234434
     :align: center

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.

.. _Markdown specification: http://frnmst.github.io/md-toc/markdown_specification.html

Conventions
-----------

- PEP 8.
- 4 space indentation.

Helps
-----


::

    usage: md_toc [-h] [-p] [-l] [-i] [-m TOC_MARKER] [-v]
                  [FILE_NAME [FILE_NAME ...]]
                  {github,cmark,gitlab,commonmarker,redcarpet} ...

    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
      -p, --in-place        overwrite the input file
      -l, --no-links        avoids adding links to the corresponding content
      -i, --no-indentation  avoids adding indentations to the corresponding
                            content
      -m 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,gitlab,commonmarker,redcarpet}

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

    Copyright (C) 2018-2019 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 [FILE_NAME [FILE_NAME ...]] 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 [FILE_NAME [FILE_NAME ...]] 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-2019 frnmst (Franco Masotti) <franco.masotti@live.com>

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/>.



