cybrkyd

Planning a Python site generator

 Wed, 03 Sep 2025 07:32 UTC

The more I use Hugo, the more I love it. However, for me, Hugo is not the easiest thing to work with. I tend to think in Python; Go is OK but working with these Go templates is a major pain, since me no know Go! It’s fairly easy to get to grips with eventually, but after 3+ years of playing with it, I’m still not in a place I would consider comfortable.

It got me thinking recently…what if? How much Python code would it take to generate a static site?

If one could have a project folder structured with their base theme, how much of a pain would this be to code?

Themes

This, in my opinion, is the most important aspect of any website. It is the front end that the world sees, so having it properly structured is the first step. The second thing to consider is how easy would those theme templates be to update/tweak/change.

For the basics, this is what I think:

theme
├── footer.html
├── header.html
└── head.html

The three files would contain nothing more than HTML and CSS, so no template code blocks which interact with the build process. That way, a change of theme is simple, as it would only involve updating these three files with no risk to breaking the site.

Content

Markdown is fairly easy to learn and use, and Python has a module called markdown, amongst others, which is capable to converting markdown to HTML. For the front matter — which I quite like — native Python is able to parse this in a few lines.

Checkpoint

With all the above, we will now have the basic structure of the pages.

<head>
<header>
<main> : the content from the markdown files will go here
<footer>

Regarding <nav>, this can be housed in the <header> as well as the <footer>. The top-level structure tags of the HTML can be inserted by the generator and closed after <footer>.

Pagination

Usually, blogs like to display posts on an index in reverse chronological order. This part can be tricky but there are many ways to do this cheaply. I’ve seen this used a lot: posts.sort(key=lambda x: x.get('date', ''), reverse=True) but the tricky part is to be able to reuse that for the individual blog posts themselves. For example, to enable the “next” and “previous” pagination between posts.

RSS and Sitemap.xml

Python is again capable here with its stdlib xml.etree.ElementTree which I favour over xml.dom.minidom.

I think that about covers everything. I’m not a big fan of tags or categories, but others might be, so that can be included as well.

The project plan is in place, time to get to work. This sounds like a great Sunday afternoon roll-your-own hackathon.

»
Tagged in: #python #PaPy

Visitors: Loading...