Due in part to my writing proclivities, that often leads into typing up documents. Being the strong advocate of free, open source software that I am in addition to a digital minimalist, I like a simple setup. Very simple, so I write in plaintext. My text editor of choice is the venerable neovim, complete with various plugins and customizations. Developer I am not, however, so my config is tailored towards writing, obviously, and I get to leverage the modal editing might of vim when needed. It very much works for me, and I can safely flail my fingers across a keyboard and have my six distinct typo variants for the word that automatically corrected.
That’s not even a joke.
As I am writing in a text editor and not a word processor like LibreOffice or Google Docs, I must turn towards markup languages. So-called “light” ones, in particular, allowing me to write in plaintext at my leisure, and then convert my work into other formats later. Markdown was my first choice, as it’s pretty much the universal standard on the internet. It’s simple, easy to learn, converts to HTML cleanly, and I can’t not mention its universality only a sentence later. There’s support everywhere, and I eagerly went to learn.
Herein begins a pet peeve for a lot of people, not just myself.
I said that markdown is simple, and that’s no lie. It was designed to be so, which is part of the issue. Markdown is very limited in scope, and was never given a set standard by its creator on purpose. This has given rise to a legion of dialects, or flavors. They all tackle shortcomings of their progenitor in different ways and extents, rarely shared between each other. Predictably, we find ourselves with a colossal mess of competing standards that begin to defeat the purpose of markdown altogether. Fun.
My chosen flavor is commonmark, which was founded with the intent to create a single, unifying markdown standard. I applaud such goals and the gradual updates to the spec over the years, but I’ll sum up my thoughts with the following:
Regardless, I have used commonmark fairly happily for several years, and continue to do so. Every post here is typed up in markdown after the physical writing, then converted to HTML using pandoc. After that, it’s a fairly straightforward task of a few tweaks to the file and I can push it out. Not quite as elegant as using a static site generator or the like, but it does the job. Just about everything I need is done.
Just about everything, being the emphasis.
While these posts are just fine in markdown, it does not cover all of my use-cases anymore. Working on more structured things like books, for example, were not as easily done with my particular flavor. Commonmark does a lot of things, but not for my evolving tastes and needs. I wanted a markup language better suited for literature on its own, rather than leaning on word processors, typesetting systems, or specialized tools and/or markdown dialects. More advanced than markdown, for sure, but not so obtuse that the learning curve is a pain, and familiar enough that I could more or less jump back in.
So I shopped around a bit and explored some of the other light markup languages. Org seemed like a really solid contender, but it’s quite married to the emacs ecosystem. Ancient and honorable that it may be, emacs has never clicked in my attempts at learning, and I’ve stuck with neovim after all this time. Though I will miss out on the wonderful world of lisp interpreters and obtuse keyboard shortcuts, my search was not over. The answer would eventually come, in the form of asciidoc.
Asciidoc feels like the cooler, more mature sibling of markdown. The one that just came back from studying abroad, and, while having a certain mystique, remains familiar. The syntax is similar but with way more batteries included, and possesses an underlying extensibility unmatched by markdown and its flavors. Asciidoc renders to HTML just the same, and the predominant implementation asciidoctor has several converters for other document formats. Having native options for PDF, EPUB, and more supported by upstream is fantastic, though there are certainly kinks to iron out. I still think it’s a great ecosystem, and wish it would gain more momentum.
That’s one of the biggest weaknesses of asciidoc, in the end. It’s super neato, but must compete with the hydra that is markdown and its widespread adoption. Never an easy task, and I refer back to the above XKCD. For all of the advantages that may apply, uprooting the established method that just works™ is usually impossible without major backing. Not that it’s a requirement or anything, since asciidoc does set itself apart. It’s much better suited for documentation and literature, without getting too overly complicated in exchange for raw power.
One might consider function over form a cardinal sin of developers. Their knowledge and expertise is undisputed, but neither directly correlate to accessibility. Especially with devs working in their free time, they are more often concerned with promoting their own workflows, not making sure their software is able to be picked up by anyone. This is the case, in part, with using asciidoc. While I enjoy and readily use it for my work, not everyone is familiar with or willing to use the command line for fear of causing global thermonuclear war. That is a big hurdle for the average user, compared to the more readily available GUI markdown tools.
Sometimes there are also seeming oversights, or somewhat niche cases that have fallen through the cracks. I have, for example, run into a peculiar problem with asciidoctor. A default stylesheet is used when converting to HTML, and you can tweak that or make your own. That’s actually really cool, and gives people a lot more leeway with their works. It’s a very nice, sane default as well, but what happens if you don’t want it? What if you only want plain HTML?
Sucks to be you, buddy.
I don’t consider this a dealbreaker by any stretch, but it stands as an annoyance. Using my preferred light markup language for my site isn’t as easy as it should be, and that irks me. All I want is plain HTML so I can use my own CSS, and I guess nobody thought of that? I’m not going to start pointing fingers at the asciidoctor devs, since I have nothing but respect for them. They have gone out of their way to create free, open source software for everyone to use, and that’s simply commendable. This is often very thankless work, and some people get these unrealistic expectations towards free content as if they’re the most important beings on the planet. That’s how you drive creators away, not help them.
That said, this isn’t me complaining. There’s nothing wrong at all with using markdown here, and the disconnect between using it and asciidoc don’t break any meaningful aspect of my workflow. I’m just going from A to HTML in the end, after all, and it felt like a fun little story to tell. Should there be anything to learn from this, if at all, it’s that you should treat your friendly, neighborhood developers with respect. Highlight bugs, suggest new features, contribute to the project if you can, or, if they take donations, donate. They’re people just like you and I, and support is always welcome.
One good turn deserves another, you know?