AI-generated (stable diffusion) ge of "cyclon writing with a pen".

The sporadic blog of David J A Cooper. I write sci-fi, teach software engineering, and occasionally say related (or not related) things.

Check out Nova Sapiens: The Believers.


I made a thing. Lamarkdown is an MIT-licenced document preparation system for Markdown/HTML, intended to address similar use cases to LaTeX (and not to be confused with static site generators like MkDocs). My Git logs tell me I’ve been working on this since late 2021, so its release is well overdue.

(As is often taken for granted in software development, this wouldn’t be possible without the use of a considerable volume of other people’s work, most notably the Python-Markdown engine.)

The documentation explains the objective motivation for Lamarkdown, but at a personal level, it’s been a journey. Near the start of my academic career, I threw myself upon the mercy of LaTeX in order to produce my thesis. This included learning the diagramming package PGF/Tikz, whose own manual alone currently extends to over 1300 pages (because, you see, it was vitally important that the snippets of text in my figures were rendered in precisely the same font and font-size as the rest of the text).

After my thesis submission, I never quite connected with the research side of academic life. But I used LaTeX for virtually everything in my teaching. I wrote LaTeX unit outlines, lecture slides, practical worksheets, tutor notes, assignments, exams, and miscellaneous documentation. For a time, I had a script to auto-generate personalised assignment feedback files for students, using LaTeX. I built up a personal library of LaTeX style files and agonised over how to create all sorts of reusable abstractions.

(The key attraction of LaTeX, for me, is its transparency, which comes about from the simplicity of its medium: plain text. Everything you do in LaTeX is visible in plain text, and there are no dark hiding places where things magically happen beyond your control. If something goes wrong, it was you that did it, and you can surely fix it with the proper understanding. And you know that this is how it’s going to be.)

For 15 years or so, I thought I’d nailed it, at least in principle.

And then, one day, there was an unfamiliar notification in my university’s learning management system, where we present all our course material to students. My lecture slides and practical worksheets were getting a rating of 0% for accessibility. The university had deployed a little system that provided automated feedback to lecturers on the accessibility of their uploaded files, ultimately to help make life a bit easier for students with limited vision, and/or using screen readers.

I had been convinced that LaTeX could do anything. But it could not do this, not realistically. From what I’ve understood (from seemingly-authoritative comments), fixing TeX/LaTeX so that it generates truly, consistently accessible documents would be a major architectural revision. That sort of thing is difficult and expensive at the best of times, but during its 4 decades of life, LaTeX has accumulated an astonishing number of 3rd-party packages, many of which would make fundamental assumptions about what LaTeX does and does not do.

What LaTeX does not do (and what all its packages don’t do either) is keep track of the semantic structure of a document. This is needed for screen readers, and perhaps (so I speculate) for other potential modes of document viewing. As I understand it, the assumption pervading LaTeX has always been that you’re making a series of page-sized vector images to be printed. All that matters is how the output looks, not what any of it means, even structurally. (I suspect it was only a happy accident, owing to the efficiency of storing text, that LaTeX output is even searchable.)

I am still learning about accessibility, but it seems clear enough that Markdown and HTML provide a much more promising path to get there, compared to LaTeX and PDF.

It’s just that Markdown hasn’t conventionally been used for the preparation of documents in the manner of LaTeX, and so there are some gaps to fill, and that’s what Lamarkdown is for.

Along the way, it’s also struck me how much verbosity LaTeX inflicts on us over Markdown, and also how much of an anachronism the Portable Document Format (PDF) is in today’s computing world. PDF is a poor cousin to HTML for nearly every purpose, other than actually printing something out (and even then, only if you really care about minute details). PDF viewers do the best they can, but (to me) viewing a document as a PDF seems like an extraneous layer of complexity that is also bizarrely inflexible. Why isn’t the document simply in the one universal format? HTML, unless you really stuff it up, is faster to load, adjusts automatically to different screen dimensions, font sizes, and even theme colours, and is much more easily subject to automated processing.

I am still ambivalent about the value of pages in PDF documents. These can serve a practical purpose beyond being printed, as a way for readers to tally their progress or identify parts of the document. By contrast and by default, HTML documents are a continuous vertical expanse of content. But there are ways to impose pagination on HTML if it comes to that.

So we’ll see how Lamarkdown goes. I’ve already used it to create a range of new course material, including presentations (by combining it with RevealJS). There’s plenty of room for improvement. It cannot yet produce EPUB files (the HTML-based format underpinning most e-books), and this would be an eminently logical thing for such a tool to do.

But it’s out there now.

Addendum: I was going to call it “Lamarquedown”, but ultimately that seemed a bit too much like a highly rarefied cry for aid on a 19th century battlefield, and not quite enough like a document preparation system.

General Jean Maximilien Lamarque (1770-1832)