GitLocker: The Coding Marketplace

Description:

mdformattoc 0.3.0

mdformat-toc

Mdformat plugin to generate a table of contents

Table of Contents generated with mdformat-toc

Description
Install
Usage

Configuration

Minimum and maximum heading levels
Disabling anchor generation
Changing the slug function

Description
Mdformat-toc is an mdformat plugin
that adds mdformat the capability to auto-generate a table of contents (ToC).
The ToC is generated in a user-specified location in the Markdown file.
Mdformat-toc, by default, creates an HTML anchor for each heading listed in the ToC.
ToC links should therefore be compatible with any well-behaved Markdown renderer (including GitLab's renderer).
HTML anchor generation can be disabled, in which case a user should configure a slug function that is compatible with the Markdown renderer used (GitHub and GitLab slug functions are currently supported).
Install
pip install mdformat-toc

Usage
Add the following line to your Markdown file.
A ToC will be generated in the location indicated by it.


After adding the indicator line, simply run
mdformat <filename>

and mdformat will generate a ToC.
Configuration
Arguments can be added to the indicator line to alter how the ToC is generated.
An indicator line with the default options would look like:


Placing more than one indicator lines in a document is currently not supported.
Minimum and maximum heading levels
A user can configure a range of heading levels to be included in the ToC (and to be "anchored").
For instance, the following configuration will only list 2nd, 3rd and 4th level headings in the ToC:


Disabling anchor generation
By default, an HTML anchor is appended to each heading.
For instance, the following heading
# Some title

might be formatted as
# Some title<a name="some-title"></a>

This ensures that ToC links do not rely on a Markdown renderer to create HTML anchors,
and makes the links universally compatible.
ToC links are by default compatible with the anchors generated by GitHub's Markdown renderer.
If your Markdown is only hosted on GitHub, you can disable mdformat-toc's HTML anchor generation:


Changing the slug function
Mdformat-toc defaults to using GitHub's slug function.
If your Markdown is not hosted on GitHub you may want to use GitLab's slug function instead:


NOTE: Unlike GitLab, GitHub requires using its own slug function in order for ToC links to work expectedly.
Creating HTML anchors and using a non-GitHub slug function is not GitHub compatible
because GitHub's Markdown renderer modifies the HTML anchors mdformat-toc creates.
The default configuration
(GitHub slug function and anchor generation)
is the only configuration cross-compatible with GitHub and GitLab.