Hypertext Documents

2026-08-02

HTML is a fantastic format. It is lightweight, textual, and a renderer for HTML is included on almost every computer these days. Moreover, it has support for almost any typographic elements you might want to use, and can be extended further via CSS to create custom document elements.

However, HTML is typically not used as an authoring format by most writers. I argue this is for a couple reasons

  1. HTML is visually cluttered. Writing HTML in a text editor manually is unergonomic.
  2. One typically wants to perform various document transformation tasks (rendering math, numbering sections, processing bibliographic citations), so it makes sense to have a “rendering pipeline” anyways.
  3. HTML is insecure. A website which processes untrusted content cannot allow arbitrary HTML.

Markdown solves these problems. However, in doing so it introduces its own problems.

  1. Markdown uses a special dedicated syntax for each typographic construct. This makes parsing Markdown quite a challenge, and additionally this privileges the built-in typographic constructs and makes custom typographic constructs second-class.
  2. Every Markdown engine supports a different subset of “rendering pipeline” operations, so if one actually uses these features the Markdown is intrinsically tied to the platform it was produced in.
  3. Markdown has many different standards, and so while it is secure it is not necessarily portable across platforms, even without “rendering pipeline” features.

Now, there are a variety of different compile-to-HTML languages which address these problems in one way or another. But what if, instead of creating yet another compile-to-HTML language, we tried to solve these problems with HTML directly?

Let’s start with problem 3. We can solve this by creating a strict subset of HTML that is known to be safe. And this can be parsed, not validated by websites which wish to accept user content, so instead of running a validation pass and then setting innerHTML, the abstract syntax tree of the parsed HTML is compiled into secure-by-construction HTML elements. However, a static site generator which trusts the provided HTML can simply copy it into a template without any parsing.

Such a subset would only consist of the fragment that goes inside <body></body>, so metadata like title and author would be embedded via microformats, like <h1 meta-role="title">Hypertext Documents</h1>.

Once we have such a subset, I propose we solve problem 1 by creating a structure editor for that subset. This is not a WYSIWYG editor for HTML, rather it should just expose the tree structure in a way that doesn’t litter the screen with open and close tags. Moreover, it should handle seamlessly converting to-and-from UTF8 and safe HTML, converting < to &lt; behind the scenes. HTML attributes could be exposed via a popup menu that appears when a node is clicked.

Then finally, let’s solve problem 2 by integrating plugins into the editor, not the rendering pipeline. For instance, section numbering could be achieved by a plugin which actually inserted section numbers into <span class="section-nr"></span> nodes at the beginning of each <hX></hX>. This sounds like the cardinal sin of “committing build results into git” but I think that in the context of documents, this is a feature not a bug because it is highly likely that in 20 years the precise build pipeline will have bitrotted, and the document should remain readable nonetheless.

I think this design opens a lot of interesting doors. It means that features like Rmarkdown’s executable blocks can be used in any publishing platform, because they just have to be integrated into the editor. It also means that the editor can be used like a notebook, with cells rerun on request from the user rather than automatically.

It also means that users can collaborate on documents without needing all of the same software installed. If I have some convoluted pipeline for producing figures from embedded Haskell code, you can still read and edit the document without needing to replicate my environment.

I’d kind of like to build this, but I’d also like to build lots of things so who knows. If you have thoughts, feel free to reach out on mastodon.

This blog post was inspired by discussion with chee and mimi