My first encounter with hypertext was in 1993. I found a DOS tool that interpreted and displayed hypertext. What little I still remember about the format suggests it has been an early precursor of markdown.
At the time, I was user of a group of bulletin boards, and authored a text informing about said group. A floppy disk containing both software and text became a major giveaway at the group’s booth at some fair.
SGML and the bread recipe
Later in the 90s, I typed my share of HTML documents.
In 1997, my mother-in-law asked me how I baked my sourdough bread. I took that as an opportunity to investigate SGML (on which HTML was then based).
SGML is a meta-format, similar to its later offspring XML. SGML is also a typical brain-child of the 90s: Quite elaborated, somewhat of a mouthful to fully comprehend and implement in software, with its own beauty and bright ideas, now considered over-engineered. From an author’s perspective, it is (somewhat) nicer to type, compared with XML.
The whole bread recipe / SGML thing turned into a labor of love and an exercise in joyful over-engineering. Where a mere recipe was wanted, I wrote down everything I considered even remotely important for backing sourdough bread. (Developers hate documenting? I actually enjoy organizing knowledge into text. I did then, and I still do.) A 13 page manual resulted, where a simple sheet of paper would have quite satisfied my mom-in-law. Just for the fun of it, I rigged up a multi-media platform, generating HTML and PDF from the same SGML source.
SGML is rarely used these days, but the old processing software is still available. As of Debian Stretch 2018, my old multi-media platform still works, essentially unchanged for 20 years. The material continues to be available on my web page. Its canonical URI has changed only twice in 20 years: First, when I obtained my personal domain. Then again some months ago, when I upgraded my sites from HTTP to HTTPS.
Markdown and YAML
Today, I enjoy using the various markdown flavors. This site is written in kramdown1.
Sometimes, one likes to author an overall document structure with content that software can interpret, but one also wants to intersperse documentation snippets for human consumption. Those documentation snippets are to be formatted nicely, but otherwise left alone and not truly interpreted by software.
Both SGML and XML offer straightforward solutions for this. Basically, a naming convention for tags is all that is needed. But one would not want to use SGML for new projects, and typing XML via an editor is not exactly a pleasure to actually do, either. If not these two, what else can one use?
When I had such a need a while ago, I tried with good success to insert markdown snippets into YAML documents. This combination is much nicer to type than was SGML. The YAML is machine-processed easily, the markdown snippets extract and format quite easily as well. To anybody running into a comparable need, I recommend considering this approach.
In case you care: The files are maintained via a private git repo, converted to HTML with Jekyll, and pushed to the server with rsync. That server is an Apache running under Docker on top of KVM2. When I push content, home-brew Docker images, or replace those on the server, I entrust rake with managing the proceedings. My setup needs no Docker registry. I standardize on Debian GNU Linux for my OS needs. ↩
I found that a KVM-based “virtual root server” that I can rent cheaply runs all the Docker containers I presently need. ↩