mdninja + markdown + jinja2 = beautiful HTML

Where I introduce a nifty script (mdninja) to convert your markdown into good looking HTML by using Jinja for templating/layout.

Created: Nov 15, 2017 by Pradeep Gowda Updated: May 22, 2020 Tagged: web · python · markdown · tools · code

I love pandoc for writing documents. However, sometime you want a lighter solution if (for whatever reason) you cannot use Pandoc.

Python has a fairly decent markdown -> HTML converter in python-markdown. But the output of markdown converter tends to be barebones with no CSS styling and lacks ways to customise the final HTML layout. Jinja2 is a very powerful and friendly templating engine for Python.

mdninja is a nice Command Line Utility that allows you to produce neat looking HTML documents by combining these two nice libraries.

Look at the github page for mdninja for details. The package is also available on Python Package Index.

This requires you to have Python3.4+. I think it’s high time for folks to move off Python2.7 for good. I did not take the time to test with/target python2. I’ll welcome PRs to that effect if you want to use it with Python 2.

Installation

pip install mdninja

Usage

Simple use:

mdninja doc.md -o doc.html

If you want to use a different template:

mdninja doc.md -o doc.html --template=stylish.html

The default template is:

<!DOCTYPE html>
<html>
        <head>
                <title>{% for title in meta.title %}{{title}} {% endfor %}</title>
        </head>
        <body>
                <h1>{% for title in meta.title %}{{title}} {% endfor %}</h1>
                {{ body }}
                <hr/>
        </body>
</html>

Metadata (like title above) is added to the document by adding metadata headers like this at the top of the file

Title: A simple document

Alternatively, you can specify the meatadata using a YAML style header too:

---
title: A simple document
---