Package: mdtoc
Markdown TOC Generatormdtocis a command-line utility to generate table of contents withinMarkdown(.md) files.SupportsPython 2.7 | 3.4 | 3.5 | 3.6 | 3.7Latest ReleasePackage StatusLicenseInstallInstall viapip install mdtoc.Basic UsageAdd these delimiters to your Markdown file:<!---toc start-->
<!---toc end-->Then, from the command line, run:$mdtoc/path/to/myfile.mdThis will overwrite the target file/path/to/myfile.mdin-place with the table of contents replacing the textin betweenthe delimiters marked above.  (The delimiters themselves are invisible comments when rendered.)  If you want to write to a new file, use--outfile.  If you want to write just the TOC to stdout, use--stdout.Technical Detailsmdtocparses Markdown "atx-style" headers only: 1-6 hash characters (#) at the start of the line followed by the header.  It doesnotcurrently detect "setext-style" (underlined) headers.TheDaring Fireball pageis the closest thing that exists to an original, canonical syntax specification for Markdown.  (The page is created and hosted by John Gruber, the initial developer of Markdown as a language.)  However, this page leaves a good amount of ambiguity.  Because of that,mdtocalso incorporates rules fromGitHub-flavored Markdown, which gives a fuller specification:An ATX heading consists of a string of characters, parsed as inline content, between an opening sequence of 1–6 unescaped # characters and an optional closing sequence of any number of unescaped#characters. The opening sequence of#characters must be followed by a space or by the end of line. The optional closing sequence of#s must be preceded by a space and may be followed by spaces only. The opening # character may be indented 0-3 spaces. The raw contents of the heading are stripped of leading and trailing spaces before being parsed as inline content. The heading level is equal to the number of # characters in the opening sequence.Please consider theGitHub-flavored Markdownrules to be the definitive empirical rulebook used by this tool.If you find a violation of that, pull requests are appreciated.You can also check live examples intests/examples.md.  This doc serves as touch-and-feel proof of GitHub's take on Markdown formatting, as well including some novel examples that even GitHub's page itself does not cover.One break from GitHub is that this tool counts tabs as spaces, for all intents and purposes.  This is different from the GitHub specification, which defines a space strictly asU+0020.Two other small notes:mdtocwill ignore comments prefaced with#that occur in Markdown code blocks (```).mdtocdoesnotcheck for congruency/continuity of header levels.  If a level-3 header comes directly after a level-1 header, that is on you and will be rendered as-is.Full Command-Line Help Doc$ mdtoc --help
usage: mdtoc [-h] [--version] [--check-links] [--outfile OUTFILE | --stdout]
             markdown_file

Generates table of contents for Markdown files.

The algorithm searches for the text blocks
between the delimiters:

<!---toc start--->
... anything ...
<!---toc end--->

The contents of the block are then replaced
by a table of contents.

positional arguments:
  markdown_file      relative or abs. path of the Markdown
                     (.md) file to overwrite

optional arguments:
  -h, --help         show this help message and exit
  --version          show program's version number and exit
  --check-links      find all hyperlinks and ensure that
                     they point to something valid
  --outfile OUTFILE  instead of overwriting the input file,
                     write to this file instead
  --stdout           don't write or overwrite any file;
                     just print the TOC to stdout

Created by Scott Frazer (https://github.com/scottfrazer).