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,
        },
    },
}
...

You can selectively disable processing of a particular heading by adding the headdown="0" attribute to it:

<h1 headdown="1">This will remain level 1!</h1>

... or using the attr_list extension:

# This one stays at level 1 { headdown='0' }

Note: This is analogous to how the Markdown in HTML extension – within Python-Markdown Extra, that comes with Python-Markdown itself – would allow you to enable markdown processing inside raw HTML blocks by inlcuding markdown="1".

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-2020 by Sascha Cowley and contributors MIT License.