Headdown: Downgrade Headings

Automatically demote those pesky headings!

What?

This is a plugin for Python-Markdown to automatically downgrade headings by a given number of levels. This is useful when, for example, using a static site generator, such as Pelican.

Why?

I didn't want to have to write standalone markdown files whose structure was dictated by the constraints of my website; nor did I want to sacrifice the structure of my website because of my markdown files. A number of 3rd party Python-Markdown extensions already exist to do this (here and here), but I was unable to get them to work with Python-Markdown 3.

How?

Download this repository and place the folder containing __init__.py somewhere on your path, or install via pip.

pip install markdown-headdown

Now, just add mdx_headdown to your markdown extensions and feel the magic.

You can optionally provide an offset parameter, which tells headdown by how many levels to downgrade all headings. The default is 1.

Note : This value will be converted to an integer and absolutised. Failure to provide a numeric option may lead to unexpected results.

For example, if using with Pelican, your configuration might look something like this:

...
MARKDOWN = {
    'extensions': ['mdx_headdown',],
    'extension_configs': {
        'mdx_headdown': {
            'offset': 2,
        },
    },
}
...

Credit

Thanks are owed to the author of mdx_downheader, whose code I examined for inspiration; and the contributers to the default python-markdown extensions, whose code I examined to get a better idea of what the manual was talking about.

This project is copyright 2018 by Sascha Cowley under the MIT License.