Since having found Markdown a few years back I have become a big fan. Markdown is a language that allows you to write plain text that can be converted into HTML.
A simple example is the header syntax, in markdown you can write
## This is a tier 2 title
Compared to the equivalent in raw HTML
<h2> This is a tier 2 title </h2>
Both of the above when rendered will produce the following
This is a tier 2 title
For a more detailed run through of what markdown is then check out this post: https://marquinsmith.com/2019/12/25/what-is-markdown/
Recently I stumbled across the video below by Pretty Printed. Pretty printed puts out many high quality python tutorials focused around using python for web development. He has many videos and how to’s on the specifics of using Django and Flask, the 2 most popular web frameworks in python.
When working with Markdown files I often find that I need to share my notes or documentation with others. This may not be a problem in some circles but handing a markdown file to general business users or clients is out of the question.
I have found myself re-writing markdown documents in Microsoft word to get the formatting and layout just so. The rendered HTML from Markdown is unfortunately never quite suitable for wider consumption. If only there was a way to add formatting to the rendered HTML output from my markdown files…
Enter the latest video from Pretty Printed. In this video he steps through creating a static site generator in python. The tool he creates builds HTML pages one at a time to publish on his website. I thought this could be used as a general tool to convert Markdown to HTML with formatting.
The associated GitHub repository can be found here.
The tool Pretty Printed created makes use of the following Python packages:
A 30,000 foot view of how this works goes as follows:
The markdown2 package is used to convert the input markdown file into HTML. The Jinja2 package then combines the converted HTML with a template file. The template file already has references to CSS and JavaScript files so everything is formatted nicely. MarkupSafe is used to ensure that no malicious code is passed through from the markup file into the HTML.
I have implemented my own version of Pretty Printed’s code here: https://github.com/quincysmiith/didactic-octo-adventure
The main function doing the heavy lifting is below.
The main inputs that need changing should you want to run this yourself are the input template file ‘panalysis-skeleton-layout.html‘ and the input markdown file ‘example.md‘
from markdown2 import markdown
from jinja2 import Environment, FileSystemLoader
from json import load
import uuid
import os
# load template HTML to use as a base for the output
template_env = Environment(loader=FileSystemLoader(searchpath='./layouts/'))
template = template_env.get_template('panalysis-skeleton-layout.html')
# load the markdown file that we want converted to html
with open('example.md') as markdown_file:
article = markdown(
markdown_file.read(),
extras=['fenced-code-blocks', 'code-friendly', 'tables'])
# create a unique filename for each output file generated
filename = str(uuid.uuid4()) + '.html'
# write output html to a file in the output folder
with open(os.path.join('output', filename), 'w') as output_file:
output_file.write(
template.render(
article=article
)
)