Simple Static Site Synthesizer (SSSS)
https://gitlab.com/intrepidhero/ssss
History
Fadedbluesky.com started as a wordpress blog. I've run wordpress on a number of sites for over 10 years and that experience meant it was easy to get up and running. But it languished in part because wordpress isn't as fun for me as it used to be. I was pining for the magic of hand coding html pages and seeing the results in a browser. The early days of the internet had a certain quaint wonder.
For a while I'd been aware of a movement of static site builders. I was intrigued by this concept. The template system that PHP gives is powerful, allowing content and presentation to be separate concerns. Even though there are many contenders in this space, many of which would no doubt meet me needs AND save me time, none came without a certain sense of "ugh. Do I really want to learn another piece of software?"
The point of fadedbluesky is to be a medium of creation for me. Learning something new can be exhilirating, but I'm already doing that all the time. What if the tool I used to create the website could itself be a part of the creative process?
Now I had the excitement I was looking for and soon the first of scripts was born. Python is my language of choice and I already had familiarity with Jinja2 templates. Meta data is stored in a YAML header in each file. I original started with ReStructeredText as a markup language but that seems to have laregly lost the popularity contest of the internet to Markdown. Since I want my content to have longevity, and learning Markdown was a small investment, I moved that way. A makefile documents my commands to build, test, and publish the site. These decisions were mostly based on minimizing up front investment and getting going quickly, while keeping to main stream tech that will probably be around for a long time.
Aside: TODO lists
I've been keeping TODO lists in a paper notebook that I carry around. I like that because it's always accessible and there is something satisfying about tangible artifacts. Below I'm experimenting with a KanBan style todo list for the site. Most things go into the planning column because there is only one of me, so implementation and test can't really happen in parallel. But if I get distracted (as often happens) in the middle of one thing I could keep track of where I left off.
| Await / Priority | Plan | Impl. | Test | Complete |
|---|---|---|---|---|
| High | Add Oasis project page | |||
| High | Switch publish to rsync | |||
| Low | ||||
| Low | Investigate automated test | |||
| Low | Are binaries ok in repo? | |||
| Low | Figure out simple DG diagram | |||
| Low | Figure out math rendering |
Update from 2021: Well that turned out to be... not so helpful. KanBan looks awful in text format. Though it seems like it would be really nice for collaboration, it adds too much friction (at least in this form) to my process. It's much easier for me to leave notes in my project source folder with "next steps", TODOs, FIXMEs, and such. Getting more systematic about this is... on my TODO list.
Design
The initial design integrated the website content with the scripts. That was a bad idea. It meant I was maintaining code and content in one repo. I couldn't easily share the code and it made it difficult to remember what was where. Hello, all the same things I should have learned from PHP a decade ago!
But it worked and I ran like that for about a year. When I next came back to it I moved all the code out into a bunch of separate modules... wait, what the heck am I doing? I've got 10 modules each with 1 - 2 functions of less than a dozen lines. What a pain to navigate. Stop over-engineering this thing!
I settled on a single python file. It imports a bunch of Python "batteries" (but not enough to form skynet, I hope) and creates a class called SSSS. I used argparse to create a CLI interface for the three functions: generate, test, and publish and you pass in the website's sitedef.py.
sitedef.py must define three functions called: gen, test, and pub. SSSS will call them with itself as the argument, which gives the function access to an API for loading markdown and templates, assembling a context (hash table) for rendering, and all the things that go into turning markdown files into HTML.
I like this separation. SSSS provides utility functions for generating the site but the website can still provide the assembly instructions. This means SSSS is probably more lightweight than a lot of static site generators and thereby gives the website more flexibility, while not providing as much automation as other frameworks. This tradeoff nicely matched my goals of being quick to write, easy to reason about and highly flexible for the future.
Future Improvements
There's still a lot of coupling between SSSS and the website. Templates (which I think belong to the site) need deep knowledge of how SSSS will provide context tables. That seems pretty brittle. Perhaps I can find ways to make this more robust later. Moving algorithms for wiki or blog generation into SSSS would good, if those algorithms can be generic enough to have wide utility and also specific enough to provide value.
QA
For the moment my QA process is to inspect the affected pages whenever I make a change. A content change to a single page is easy to check. Sometimes a change could affect lots of pages (like a code or template change), then I might just check a few. This process will get unwieldy as my site grows and I'll be more likely to miss stuff so I'll be researching automated testing. Low hanging fruit my be to check for broken links or missing static content.