This 'old' blog and how it works

If you were to tell me at the time of writing "something's new in the air" that I would be running roughly the same system 10+ years into the future...

I would most likely be a bit proud with equal parts bewilderment.

If it is not broken, don't fix it

This is a claim that appears anytime someone tries to resist proposals to modify the modus operandi for systems that have momentum.

Ultimately, the momentum in this context is that I dreamed up a pattern for how I wanted to write content on the web and stuck with it. It does enough, and is flexible enough given my demands (which are very minimal).

The true measure of systems...

...is how much time you need to spend to keep them going.

No, I don't really want to use this website as an example of this measure. Updating the templating does require careful manual testing and planning which takes some time.

I've thought of ways to port over the source of this website to a different scheme which has different properties before. I came to the conclusion that the net effect is exclusively going to re-arrange the 'hard work' and ignore the difficult problems.

The difficult problems in my case happens to be just writing... and the approach that has been settled on works quite well with my default tooling.

The decisions I made 10+ years ago yielded a simplicity of templating and content generation. At the core of this site is a set of python scripts that have been roughly the same since their conception. Besides porting them to use python3, applying general refinements, and small feature changes, it's the same original idea extended from being used for over a decade¹.

How this blog works

This site is hosted by an nginx server, which is serving a directory of static files generated from a single repository which looks something like this:

Elided source repository

bannatech
  ├── sources/
  │     ├── about/
  │     ├── categories/
  │     ├── home/
  │     ├── blog/
  │     │     ├── 00_hi.md
  │     │     ├── ...
  │     │     └── 24_this_old_blog_and_how_it_works.md
  │     ├── projects/
  │     └── projectshome/
  └── templating/
      ├── data/
      │     └── static/
      ├── includes/
      ├── templates/
      └── pages.yml

The content of this site is the sources/ directory - and that is a collection of serialized markdown files with embedded metadata for preserving ordering, time-stamping, titles, and descriptions.

A separate tool is responsible for consuming these markdown files and generating a set of ugly JSON files which represent the content in a format that is consumed by the pnbp blog module.

The templating/ directory contains the pnbp project which uses uses the assembled JSON content built from the sources/ directory. This is what ultimately generates the html files for the site.

This pattern works for me

The templating tool is lightweight and portable enough, I can re-generate the entire site very quickly. I can even write a script to watch for changes² to either templating/ or sources/ and generate the site into a local directory where I'm running a local HTTP server, which can be easily done through running a python module from the shell: python3 -m http.server 8080.

Written content is separate from the templating world, thus I am not relying on odd quirks or behaviors: The blog is realistically a collection of markdown files with associated metadata. This also means that I can support different templating targets which generate from the same source, if I want to publish a gemini site, or produce an rss feed, for example. Neither of these has been done, and I don't imagine it would be very difficult.

The templating system is quite flexible, and there is no pressure from the outside to conform to any standard or fit other workflows (besides maybe firefox reader mode...). Most importantly, it is just me using these collection of tools to publish to this website. This is an exercise of implementing the 'hard work' involved in order to publish content, initially to the web.

This pattern might not work for you

... or me either, and I've yet to find out why

There is a big assumption here, and that assumption is python - the snake in the room - per se.

The portability of python is riddled with pitfalls³, and if there were to be specific versions of python-markdown or pyyaml that I would need to run this site, I would most likely consider a different set of tools to re-implement pnbp.

Additionally, the volume of data here is rather sparse, thanks to my efforts to avoid writing whenever possible. Unfortunately it seems like there are cases where big JSON⁴ is seemingly everywhere.

The beauty of owning the source of your data

The beauty of information is that, if you control the information you intend to share, the ways in which you can store and process that information is practically endless. The limitations come in when you want to publish to other entities.

I wanted to spend some time to write this out to capture some of my thoughts around this site. I think of this website as a creative process to express the strengths of tools at our disposal.