Metadata-Version: 1.2
Name: md_toc
Version: 7.0.1
Summary: A 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
Description: Markdown Table Of Contents
        ==========================
        
        |pypiver|    |license|    |pyver|    |downloads|    |gitter|    |dependentrepos|    |buymeacoffee|
        
        .. |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
        
        .. |gitter| image:: https://badges.gitter.im/md-toc/community.svg
                      :alt: Gitter
                      :target: https://gitter.im/md-toc/community
        
        .. |dependentrepos| image:: https://img.shields.io/librariesio/dependent-repos/pypi/md-toc.svg
                              :alt: Dependent repos (via libraries.io)
        
        .. |buymeacoffee| image:: assets/buy_me_a_coffee.svg
                           :alt: Buy me a coffee
                           :target: https://buymeacoff.ee/frnmst
        
        Automatically generate a compliant table of contents for a markdown file to 
        improve document readability.
        
        Video
        -----
        
        .. image:: https://asciinema.org/a/313824.png
             :target: https://asciinema.org/a/313824
             :align: center
        
        Description
        -----------
        
        The table of contents (a.k.a: TOC) generated by this program is designed to 
        work with several markdown parsers such as the ones used by GitHub and GitLab.
        
        When used with the in-place option this script will write the TOC at the first
        occurrency of a marker. The default marker is ``<!--TOC-->``, which, being 
        an HTML comment, will result invisible after the markdown file has 
        been translated.
        
        By default titles up to three indentation levels (in HTML: ``h1``, ``h2``, 
        ``h3``) will be included in the TOC but the user can decide to keep all
        possible levels.
        
        md_toc makes it is possible to generate ordered and unordered TOCs.
        In both cases each element of the TOC is by default a
        link to a paragraph in the web page. It is also possible to generate 
        a non-linked version of the TOC. 
        
        If the user wants it, there is the possibility to ignore space indentations
        within the TOC and to skip an initial number of lines from the markdown file.
        
        Rules for generating the TOC are determined by the selected 
        markdown parser. md-toc aimes infact to be as conformant as possible in 
        respect to each one of them. This was possible by studying the available 
        documentations and by reverse engineering the source codes.
        
        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
        
        API examples
        ------------
        
        md-toc has a `public API`_. This means for example that you can you easily 
        build a TOC within another Python program. The easiest way to build one 
        for a markdown file is:
        
        
        ::
        
        
            >>> import md_toc
            >>> f = open('foo.md')
            >>> print(f.read(), end='')
            # this
            ## is
            ## a
            ### foo
            #### booo
            ### foo
            ## file
        
            ## bye
        
            # bye
            >>> print(md_toc.build_toc('foo.md'), end='')
            - [this](#this)
              - [is](#is)
              - [a](#a)
                - [foo](#foo)
                - [foo](#foo-1)
              - [file](#file)
              - [bye](#bye)
            - [bye](#bye-1)
        
        
        .. _public API: https://frnmst.github.io/md-toc/api.html
        
        CLI Helps
        ---------
        
        
        ::
        
        
            $ md_toc --help
            $ md_toc github --help
            $ md_toc redcarpet --help
        
        
        License
        -------
        
        Copyright (C) 2017-2020 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/>.
                  
        
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.5, <4
