m. c. de marco: To invent new life and new civilizations...

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.

Client-side: mdwiki

In fact, the first software I tried, the inaptly named mdwiki (source on GitHub), seemed perfect. It was pretty and themable (thanks to Bootswatch), it was not a wiki but a single HTML file (if stuffed to the gills with JavaScript), it could open my files from my notes directory (symlinked in from Dropbox), and it even created a linked table of contents for navigation within each markdown file, like Wikipedia has.

It took me a few days to run into mdwiki’s downsides: even though I was running it from a web server (the one built into my Mac, not a public one) rather than using the flakier method of just opening the html file in my browser, it was slow. Depending on how you navigated around the wiki, it often wouldn’t even open the page for thirty seconds or more. The local navigation block left an ocean of whitespace, which I sometimes alleviated by narrowing the browser window. And, most trying of all, the navigation menus had to be hard-coded by hand; there is no way to access the filesystem from client-side JavaScript in order to index it automatically.

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.

Singularity CMS

I found perfection, again, in Singularity CMS, a “one-file” PHP CMS by Christopher Su. GitHub revealed that it was three years old, and, if you look more closely, that it was not really a one-file solution. Markdown parsing and theming don’t happen in PHP (where some other CMSes do it), but on the client thanks to Strapdown, a JavaScript package including marked, the Bootswatch themes, Bootstrap, and more. PHP never goes out of style, but Strapdown was last updated two years ago, so when I went in to make some changes, I had to be sure to use the old Bootstrap classes.

Singularity wasn’t so much the perfect CMS as an incomplete example of how I would write my ideal CMS. I extended it with directory indexing (in PHP) and a page-level table of contents (in JavaScript). I tried to resist the urge to update the Strapdown JavaScript components, because Singularity already did everything I wanted it to do, even if I’d had to hack it a bit to get there.

SCMS

In the end, though, I gave in to the desire to modernize and made my own simple CMS, SCMS, in which my hacked-in menus and 404 behavior are a bit better integrated, all the JavaScript is updated to the latest versions, and more bootstrap components are available. I [originally] put it on BitBucket so I could use Mercurial instead of Git for version control.

I haven’t quite wrapped it up yet, though it’s well-documented and (still) does everything I want. I’ve already replaced Bootstrap with Bootstrap without jQuery, but I think Bootstrap itself is just too heavyweight for displaying translated Markdown plus a few menus. So the next feature will be a simpler, customizable theme with even less JavaScript—if I don’t get distracted before then.

Update (8/13/2015)

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!

Update (7/1/2020)

SCMS moved to GitHub along with all my other BitBucket projects, due to the Circular BitBucketting.