Automatically demote those pesky headings!
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.
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.
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="0">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"
.
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.