As a "micro-teaching" task during my PGCE, I had to solve some kind of problem, and then teach the rest of the class how I solved it in a short, 15-minute lesson. I'd been meaning to write a simple program that would help me generate the pages for blog posts on my site, and make a neat little list of them on the "blog" page, so I figured this was the ideal problem for me to solve! I implemented most of it in an evening, and while I was waiting for an appointment. This post documents its creation, and explains how it works.
I started my site sometime in late 2024, fleshing it out more in the early summer of 2025. I decided to split it into the main six pages you see in the navigation bar now, as I figured they covered all of the bases of what I'd be using this site for. Anyway, I fleshed out the "home" page first, and later made good use of the "sites" and "books" pages over the next year or so, and spent a few evenings fleshing out the "hardware" page. "misc" was empty for a while, before I relocated some of the silly little things I had on my home page there, but that's sort of what it was for anyway.
All of these pages saw some use, but the "blog" page was always pretty empty, populated by some text saying what the page was for (if it wasn't obvious anyway), and a single line stating my intentions to make a simple content mangaement system to generate individual blog post pages from some easy-to-write source file, and to catalog them all on the "blog" page. For a number of reasons (none of them particularly excusable), this never happened, and the blog page remained a monument of apathy for over a year!
Anyway, earlier this month (September 2026) I started a PGCE (teaching qualification) at the University of Worcester, specialising in (what else?) computer science. One of the activities we had to do was a little "micro-teaching" session to our classmates, where we had to teach them how we solved a particular problem. The example given by Mr. Hunt, our tutor, was how he created a GPS tracking collar for his dog, to see how far it travelled on the walks he took it on (that might sound a bit pointless, given you could just use the step counter on your phone, but all the zigging and zagging dogs do really does add up!) He talked us through the problem, and how we went about solving it (which is documented on Instructables here).
Of course, in order to solve a problem and teach someone how I solved it, I actually had to find a problem to solve first. It didn't take long before I remembered the blogging system I never got around to implementing, so I figured I could exploit this opportunity to kill two birds with one stone!
There are many languages that would be good for a problem like this (and, equally, many that would not). I had originally planned to write this generator in AWK, but decided against it as I don't know it that well, and didn't really have time to learn it, simple though it may be (after all, we only had two days to solve our problem and plan a short micro-teaching session around it!). In the end, I decided to go with Python, as I've been working with it a fair bit lately in the PGCE (it's the most common language used for teaching programming at GCSE), and this problem is one Python could handily solve. I might re-implement it in Perl someday, but that's a future problem!
My original intention was to be able to write my blog posts in MarkDown, and for this MarkDown to automatically be translated into HTML, and then combined with a template to generate the final page for that blog post. Additionally, I wanted all of these blog posts to automatically be listed in reverse chronological order on my main "blog" page, because doing that manually would be a very boring job, and I'm not the biggest fan of being bored.
I quickly decided that writing a MarkDown to HTML converter would be a bit much to implement in such a short timeframe, and I'm quite keen to do everything on this site myself, rather than using external libraries, which often take the fun out of programming in my opinion (at least for relatively simple tasks like this, where Python is sufficiently powerful to handle the necessary tasks itself). Instead, I elected to write the blog post contents in incomplete HTML, and have them combined with a template file which had the rest of the contents that would be common across all pages. I called these incomplete files ".slice" files, as they were "slices" of a full page.
Each slice file consists of the main blog text enclosed in HTML paragraph tags, as well as a div of class "overview", which has the overview text to be displayed in the post's entry on the "blog" page. This is very basic, and more features will be added (e.g. nice title, proper date stamp), but this basic system is enough for the simple micro-teaching demonstration it was for. In any case, those features will probably have to wait for another year and a half, if I am to continue with the original pace of development!
With the standard for how I would store my posts loosely decided on (though it would be tweaked and corrected as I refined my implementation), I decided to get programming.
I started just by writing comments outlining the key functions the script should perform, and the order in which they would likely occur. I think this is a useful step to take when planning out a program, as it gives you clear, smaller goals to achieve, rather than one big overarching task of "Do The Thing". To use some subject-specific lingo, that's an example of decomposition - write that down, it'll be on the test! These goals were as follows:
For each blog post...
And finally...
With my goals set, I began to lay the groundwork that would facilitiate the completion of these goals. The main thing I needed to get started was a listing of all the .slice files in a given directory, and the easiest way I found to do this was with the "glob" library, for UNIX style pattern-matching in directory listings. This would allow me to get a list of all .slice files with the line "slices = glob.glob("*.slice")". Result!
Most of the action happens in a for loop, which iterates over the "slices" list created earlier. For each slice file in the list, the following is done:
The first step is simple enough to do, and is done inline in the loop with a few lines of code, storing the contents of the current file into the variable "slice_txt". The rest are a little more involved, however, so I decided it would be best to implement major parts of these steps as functions, to make the main loop a little more managable.
"extract_overviews()" is the first function used in this loop, and it takes the raw text from the current slice as a parameter, and returns just the text inside the overview div. This is then stored in an "overviews" dictionary, with the name of the slice file (minus the file extension) as the key.
The next major objective is generating the HTML from the slice text. This consists of a few steps, but the most complex is combing the slice text with the template file text, which is thus put into its own function: "insert_slice()". This function reads the contents of the template file into a variable (in fact, it does this every time this function is called, which is quite wasteful - it only needs to be loaded once at the start of the program). It then uses a built-in string method called "splitlines()", which takes a multi-line string and turns it into a list, which each line being a list item - this makes combining them a lot easier!
Once the template and slice text are stored as arrays, "insert_slice()" then iterates over each line of the template file text until it finds a line reading '
After this is done, the contents of the combined template and slice lists are iterated over, and appended to a string called "final", meaning that the template and slice text are now one big long string that can now be just written to a file. This "final" string is returned by the function, and written a HTML file with a name corresponding to the appopriate slice file.
Of course, all of these steps are part of the main loop, and repeated for each ".slice" file in the directory.
I decided to put this functionality in its own function, "create_list()", with the overviews dictionary being passed in as a parameter, as it contained all the information needed. This loads a template file for the main "blog" page into a variable called "buffer", splitting it into a list of strings (similar to "insert_slice()"). A for loop iterates over this buffer until it finds the the list div, and then another for loop iterates over each item in "overviews".
This for loop creates and inserts a listing for each blog post, generating a hyperlink to it (with a simple function called "make_link()", which generates a HTML anchor element from the blog name in "overviews").