"some subheader text."

how the blog was built

posted , updated
tagged: python


Table of contents.

Hereby I talk through writing my own blog engine. There are many excellent ones out there, but to customise any of them takes so much understanding of how they work, the template and theme engines they use, that its easier to just use them exactly as is with an existing theme.

I wanted my own custom static blog, which played well with jupyter notebooks and markdown files, as well as a reason to do some python coding, so here goes yet another python blogging engine.

This post documents the process of building this blog. The main goal is to put markdown and jupyter notebooks in a folder, and build a static site which gets autoupdated on github pages or netlify. Just like hugo, jekyll, gatsby and so many others!

blog engine

Its straightforward to read a set of markdown posts and convert to python. I am using python to read the posts with python-markdown to parse them into html, complete with inline syntax highlighting.

Key tools used:

Below are notes for the specifics used.

parsing markdown

Python markdown

Start a server from cli:

python -m http.server

notebooks to markdown

I started with nbdev to convert notebooks to markdown, but it slowed down rebuilding the blog a lot, and its pretty complex. So in the end I've stuck with nbconvert. Some useful tips:

code highlight

python markdown has pygments built in, which has a bunch of styles. To generate the css:

pygmentize -S default -f html -a .codehilite > codestyles.css

But on second thought decided to can this and go with highlightjs for now as it speeds up builds and keeps the html clean (at the cost of loading more javascript).

One thing to investigate is how to make the output cells of jupyter notebooks blend into the main website. This seems to require some css trickery.


I'm no longer familiar with html, even though I build my first weblog on geocities way back in 1997/8. So we have now reached html5.


Frameworks I looked at:

Search. I want search.

Considered at

So step one is to build a search index - which my script does as a json file containing all the post attributes I want searched.

Github actions

Github actions add superpowers to a repo - they can be set to be triggered at a time interval or on every code push to a branch. To make a github action: Save a github approved formatted yaml file to .github/workflows folder and it should run on every push. For this blog my actions:

Misc stuff


Some unicode fonts have emojis built in, so ways to enable emoji is:

Emoji test:

twitter embed

This should show a twitter tweet embedded inside the page:

Sunsets don't get much better than this one over @GrandTetonNPS. #nature #sunset pic.twitter.com/YuKy2rcjyU

— US Department of the Interior (@Interior) May 5, 2014

testing syntax highlight

from mako.template import Template
from mako.lookup import TemplateLookup
lookup = TemplateLookup(directories=["templates"])

# make the big picture templates
for tmpl in ["index.html"]:
    template = lookup.get_template(tmpl)
    html = template.render(posts=posts).strip()
    path = path_publish / tmpl
    print(f"wrote {tmpl} to {path}")

# write all the posts
template = lookup.get_template("post.html")
for post in posts:
    html = template.render(post=post).strip()
    path = path_publish / f"{post.slug}.html"
    print(f"wrote {post.slug} to {path}")