The Search for a Simple CMS
Inspired by a couple of blog posts at jcbsnd.com and a long file of notes in Markdown from my endless struggle to understand git, I decided I wanted to gather all my notes together into some sort of more easily readable system.
I tried out some of the dedicated software he mentioned; I was most impressed with nvALT, but it also impressed upon me how little I wanted to switch to another program when I’m most likely to be taking my notes about something in the next Emacs buffer over, or reading about it in the next browser tab over. What I really wanted to do was edit my own flat files, in markdown, in my usual editor, then display them in my usual browser. Anything more than that—in-browser editors, user authentication, etc.—was a minus, not a plus.
Similarly, I wanted my setup to be based on the existing file system hierarchy of my markdown files; they shouldn’t need to be integrated into a complicated directory structure, never mind one also filled with extraneous template files and the like. Besides leaving my directory structure untouched, no changes should need to be made to my markdown files themselves—at least, no changes that weren’t clearly improvements over my existing markdown formatting. To put this requirement in HTML terms, I didn’t want to have to clutter my notes up with wrapper divs. Someday (probably all too soon) I will want to do something completely different with my markdown notes, so I want them to remain in the most portable format possible.
I was not expecting to have to write my own note software for something as simple as displaying some markdown in a browser. I figured someone must have done it already. GitHub is littered with just such small, easy, unnecessary yet handy projects.
Once upon a time, I wrote a PHP “wiki” (in the sense of mdwiki) that automatically indexed itself. It’s still running (locally), but it was built to display existing HTML files, not parse markdown into HTML, so it won’t work out-of-the-box for my current project. I had some helper scripts for it to turn Mac-style .webloc links into HTML files listing those links, or to display a directory of images in a single HTML file. So I might have considered rewriting my helper scripts to semi-automatically generate mdwiki’s navigation menu, but for the browser issues I was experiencing.
Once upon a time, I wrote an xml encyclopedia to keep track of my science fiction universe. It was pretty and easily navigable and indexable despite being a single long xml file manipulated with stylesheets. But my encyclopedia ran into browser dependency issues; xml stylesheet support was spotty at the time, and only some browsers did everything I’d coded it to do. It was so cool that I was willing to use the browser it worked with, but mdwiki is not quite that cool. So I started looking again.
Server-side: Node, PHP, etc.
There are a lot of simple CMSes based on node.js, and I even tried Raneto. (It wasn’t pretty enough.) But I also didn’t want to keep a separate node server running when I already have apache running to mirror my website (and host my old wiki). I considered Ruby or Python, but the CMS pickings there are slim. Also, I wanted a framework that would run in my vanilla apache install, and keep working after the OS inevitably gets
worse updated. That, sadly, was PHP.
Google yielded an impressive collection of PHP CMSes, most of which disappointed me in the end. A better resource than straight googling was this list of Flat File CMS Systems, because it hit on my major requirements: PHP, markdown, open source.
All the PHP stepchildren of Pico…
According to Google, there was already a perfect, popular choice: Pico (source on GitHub), the poster child for my sort of simple PHP CMS. Sadly, though, it didn’t quite run. I didn’t hack at it very long because googling my issues revealed that Pico was abandoned and the community scattered. The author had moved on to Baun, and the legal owners (who knew you could sell a CMS?) were AWOL.
Baun was shiny and brand spanking new, but a huge codebase with functionality I didn’t need. I gave up on it when I realized it required YAML headers in my markdown files.
Phile was another massive Pico by-blow, so I gave it a try, but it had lost all the simplicity of its parent CMS.
…and then some!
Grav was the size of Jupiter, but it looked so professional and supported I had to try it out. I couldn’t get it working and my issues were not addressed in the troubleshooting docs. I gave up on it quickly because, while pretty and highly active, it was also clearly much more than I needed.
So I went back to the old, simple stuff. The Stacey website was up when I looked into Stacey, though github proved more reliable over time. The only extension Stacey allowed was
.txt and all my files were named
.md, but Stacey was so lightweight that I started rewriting the code. Looking at the source led to looking at the documentation, which revealed the directory structure imposed on content and some extra YAML files that turned me off Stacey.
Fizl sounded promising, even though the code was old, the website was gone, and I had to get the demo and documentation out of the Wayback Machine. Despite a timezone fix stolen (IIRC) from Stacey, I wasn’t able to get the old boy running.
I also considered Automad, though the demo theme looked a bit odd, and Yellow, because it looked so pretty, but I didn’t get as far as installing either one.
The next steps got bogged down in Ajax and menus, but I found a prepackaged solution to my problems, h5ai. Nominally it just improved Apache’s default menus, but it will actually render Markdown, and all it takes is a one-line
.htaccess file to serve it from my local Apache. That was much quicker than wrapping up SCMS, and somebody else wrote all the PHP—a win-win solution!