Header Downgrader Extension for Python Markdown.

When working with markdown files, sometimes you need to “downgrade” your headings for styling purposes. A good case scenario for this is using markdown with static site generators, for example, Pelican.

Given a piece of markdown like this:

# This is header 1
## This is header 2

Python Markdown will generate the following HTML:

<h1>This is header 1</h1>
<h2>This is header 2</h2>

With this extension enabled we obtain this instead:

<h2>This is header 1</h2>
<h3>This is header 2</h3>

Easy!

How to install

pip install markdown-downheader

Tested with Python 2.7 and Python 3.5

It requires the awesome Python Markdown package, tested with Markdown 2.6.5

Usage

Directly from python

from markdown import markdown
text = '# hello world'
markdown(text, ['downheader(levels=1)',])

From the command line

echo '# hello world' > test.md
python -m markdown -o html5 -x 'downheader(levels=1)' -f test.html test.md

Note: Some static site generators, like Pelican, can use markdown extensions. You just need to install the pip package and provide the name of the markdown extension (in this case the name is simply ‘downheader’). For example, for Pelican just add this to your pelicanconf.py file:

MD_EXTENSIONS = ['downheader']

As of Pelican 3.7 you have to define the Markdown extensions as a dictionary. Here is an example:

MARKDOWN = {
    'extension_configs': {
        'markdown.extensions.codehilite': {'css_class': 'highlight'},
        'markdown.extensions.extra': {},
        'markdown.extensions.meta': {},
        'downheader': {},
    },
    'output_format': 'html5',
}

To pass a value, you can use the following:

# Markdown Plugins
MARKDOWN = {
    'extension_configs': {
        'markdown.extensions.codehilite': {'css_class': 'highlight'},
        'markdown.extensions.extra': {},
        'markdown.extensions.meta': {},
        'downheader': {'levels': '2'},
    },
    'output_format': 'html5',
}