
\documentclass[12pt]{article}
\usepackage[T2A,OT1]{fontenc}
\usepackage[default]{cantarell}
\usepackage[a4paper, top=20mm, bottom=20mm, left=20mm, right=20mm]{geometry}
\usepackage[utf8]{inputenc}
\usepackage[russian, english]{babel}
\usepackage{tabu}
\usepackage{hyperref}
\usepackage{parskip}
\usepackage{graphicx}
\usepackage{tabularx}
\usepackage{float}
\floatstyle{boxed}
\restylefloat{figure}
\usepackage{setspace}
\onehalfspacing
\author{Artyom Bologov}
\date{\today}
\title{Write Hypertext, not Plaintext}
\makeatletter
\def\endenv{\expandafter\end\expandafter{\@currenvir}}
\makeatother
\begin{document}
\maketitle

I visit Derek Sivers’
\href{https://sive.rs/}{website} from time to time. Every time I do, I discover he had

\begin{itemize}\item written some half a hundred new blog posts,
\item moved to another place,
\item and started a new diet/philosophy/routine/book.
\end{itemize}

He’s too productive for a human, but that’s a topic for a different time.
The topic for today is his choice of data formats.

\section*{All You Need is Plaintext} \label{all-you-need-is-plaintext}

One of the posts that started me the most was Derek’s
\href{https://sive.rs/plaintext}{Write Plain Text Files}.
Storing all of one’s life, writing, and data in plaintext files is too appealing to ignore:

\begin{figure}[h!]\begin{quote}
  They are the most reliable, flexible, and long-lasting option.
\end{quote}\caption{Derek Sivers, Write Plain Text Files}\end{figure}

The problem is: Derek’s are not really plaintext files.
He invents his own metadata headers.
Date, tags, and title—pieces of information that don’t belong to text-only files.
Ad-hoc extension to the headers-and-paragraphs structure everyone does in plaintext.
Waaaaaait, the headers-and-paragraphs structure is ad-hoc too!

Plaintext is not enough.
The moment you start adding metadata, links, lists, and quotations—you’ve transgressed.
It’s richtext now. The worst kind of richtext:

\begin{itemize}\item non-portable,
\item unstandardized,
\item and likely inconsistent across time.
\end{itemize}

\paragraph{The perfect plaintext file} \begin{quote}
The most readable plaintext file that I’ve ever seen is
\href{https://hipster.home.xs4all.nl/lib/scheme/gauche/define-syntax-primer.txt}{this define-syntax tutorial}.
But even there, the syntax, though perfectly readable, is author-specific and non-portable.
It’d benefit from being HTML instead, but oh well.
\end{quote}

\section*{The Plaintext is a Lie} \label{plaintext-is-a-lie}

\emph{I have to clarify}: there are actually two types of “plaintext” we’re talking about here.
Both Derek Sivers and
\href{https://plaintextproject.online}{Scott Nesbit}
make the mistake of conflating these types.
What plaintext devotees usually mean is a storage format, as in binary-versus-plaintext.
That’s the first part of the MIME type: \verb|text/*|.

Then, there’s a second part of MIME: subtype. That’s where it gets ugly (citing
\href{https://plaintextproject.online/articles/2017/07/11/matters.html}{Scott Nesbit}):

\begin{figure}[h!]\begin{quote}
Believe it or not, plain text is used everywhere. Even when you don’t see it. Where? In the source code for software, web pages, blog posts and articles (like this one), configuration files on your computer, and more.
\end{quote}\caption{Scott Nesbit, Why Plain Text Matters}\end{figure}

And then:

\begin{figure}[h!]\begin{quote}
I can, for example, open a text file that I created in 1991 using any modern text editor — whether on my desktop or on the web or on my smartphone. All the information is there, and I don’t lose any formatting.
\end{quote}\caption{Scott Nesbit, ditto}\end{figure}

Plaintext is code, web page sources, configuration files, etc...
And you can also open and preview it all in your editor?
This blog post you’re reading is a pure horror when compiled
from
\href{run:this-post-is-lisp}{Lisp}
to HTML (
\href{run:this-post-is-cpp}{with C preprocessor},
actually. And it’s pretty now!)
The code that supports it is quite unreadable because I didn’t really care about the style of the code hosting my blog.
And then, this supporting code is Lisp, which causes nausea
for the programmers used to their slightly-incompatible C-like syntax language.

There are really two kinds of plaintext.
Plaintext-the-storage-type and plaintext-the-display/markup/software-subtype.
The former is eternal, and the latter is as ephemeral as the software/human processing it.

That’s why I’m taking an “anti-plaintext” stance here.
You must use plaintext as a storage type, but, more important than that, you have to pick the most reliable subtype.
Otherwise, all your “plaintext” files from 1991 get too ugly to understand 😛

\section*{Screw .TXT, All My Homies Use Markdown} \label{screw-txt}

So plaintext is not enough, and one needs a structured and metadata-aware text format.
Most of my fellow programmers realize that at some point.
They usually convert to Markdown soon afterward.

Markdown is the de facto standard for \href{"https://en.wikipedia.org/wiki/Zettelkasten"}{Zettelkasten} notes,
\href{https://gohugo.io}{blog posts},
and project docs.
Obsidian supports markdown, GitHub supports it, VSCode supports it—everything supports it.
It has headings, lists, links, metadata headers, HTML injection,
and other
\href{https://github.github.com/gfm}{platform-specific incompatible goodies}.
\href{https://git.sr.ht/~xigoi/markdown-monster/blob/master/monster.md}{Like, a lot of really platform-specific behaviors}.
And it looks nice when rendered!

One can argue for a particular richtext format, like
\href{https://orgmode.org}{Org Mode}
possibly with
\href{https://gitlab.com/publicvoit/orgdown}{Orgdown},
YAML, or Wiki, each with its benefits.
But, essentially, everyone is okay with richtext in whatever format they have.
Obsidian, Roam, Brain, and other knowledge systems make these atomic richtext files interconnected.
They bring structure and hierarchy to them.
One’s Markdown files are a self-sufficient knowledge web now.
But, for a paranoid like me, these systems are no consolation.

\section*{Knowledge Webs. Better ones.} \label{knowledge-webs}

Obsidian will end.
Myspace, Google Reader, and dozen other vital tech products did.
Once it’s gone—your knowledge web is at best scattered, at worst destroyed.
Markdown files you have are subtly incompatible with the new knowledge system.
Your reference system is lost.

One of the social tech-agnostic solutions
(because social solutions are superior to technical ones)
would be to pick another, more reliable, referencing system.
Like academic one—with a dozen metadata fields unique to the given paper/post/media.
It’s been there for an eternity, and will likely last—the academy is not letting reliable systems go.
And there are technical solutions to keep your references clean and consistent.
Like
\href{https://zotero.org}{Zotero}
\href{https://citationmachine.net}{and Citation Machine}.

But, even with these citation and referencing tools, keeping your knowledge base up to date is hard.
You have to update references, load files, generate links, and interface with the document/richtext editor of choice.
Would be nice to have something with (back-)linking, formatting, and plaintext-like data persistence. Something like...

\section*{Hypertext} \label{hypertext}

The academy made a live-changing gift to modern civilization in the nineties.
HTTP, URI, and HTML are simple yet reliable foundations for the modern Internet.
For a reason:

\begin{itemize}\item HTML has its roots in the academy with its semantic markup and referencing fetishes.
\item HTTP is plaintext in the most reliable meaning of plaintext
\item and URI is a system for unique, linkable, and readable data references.
\end{itemize}

HTML was (and still is) intended to replace printouts, libraries, and opaque PDFs.
\href{https://developer.mozilla.org/en-US/docs/Web/Guide/Printing}{CSS follows suit}.
\verb|<a>| tag and a \verb|href=URI| give one the full power of referencing unique data,
in the minimum amount of characters possible.
Tables, lists, paragraphs, and other structural tags (especially in HTML5)
cover all the possible needs of a writer, followed by
\href{https://developer.mozilla.org/en-US/docs/Web/HTML/Element/cite}{citations},
\href{https://developer.mozilla.org/en-US/docs/Web/HTML/Element/q}{inline}
and
\href{https://developer.mozilla.org/en-US/docs/Web/HTML/Element/blockquote}{block/multiline quotations},
\href{https://developer.mozilla.org/en-US/docs/Web/HTML/Element/abbr}{abbreviations},
\href{https://developer.mozilla.org/en-US/docs/Web/HTML/Element/time}{dates},
\href{https://developer.mozilla.org/en-US/docs/Web/HTML/Element/address}{addresses},
and whatnot.

I’m getting <abbr title="Yes, stoned as in high on whatever drugs—it’s that exciting.">stoned</abbr>
every time I open
\href{https://developer.mozilla.org/en-US/docs/Web/HTML/Element}{HTML}
and
\href{https://developer.mozilla.org/en-US/docs/Web/CSS/Reference}{CSS} references on MDN or WHATWG.
Seems like they anticipated every single use-case for semantic pages on the Web.
HTML is Markdown but with all the possible metadata one needs.

If you’ve read this far, you’ve probably seen the silcrow signs near headings and pilcrow signs near paragraphs.
These link to the sections and paragraphs they precede
I’ve reinvented Bible-like linking, and I’ve done it in the only system that was flexible enough to do that: HTML.

Update Dec 2023: I removed the pilcrow signs,
because they were too noisy and hard to re-implement
in
\href{run:this-post-is-cpp}{C preprocessor}.

Update Mar 2024: Pilcrow signs are back!

Your data is safe in HTML because it’s still plaintext.
Your data is portable in HTML (even if it’s my ugly sort of HTML) because it’s not an ad-hoc plaintext extension.
Your data is pretty in HTML because HTML+CSS is a plaintext format intended for display (even if it’s an audio “display”, ahem.)
Your data is meta-enriched in HTML because there’s a tag,
\verb|<meta>| header,
or attribute for any type of metadata you can imagine.
Your data is a knowledge web in HTML because it’s all interlinked and machine-parseable.
By default. Forever.

\emph{Write Hypertext Knowledge Webs, Not Plain Text Files.}

\section*{Interlude on Tools} \label{interlude-tools}

Update Jan 2024:
I’m saying “portable” and “pretty”, because hypertext as an idea and HTML as an implementation are defined as:

\begin{figure}[h!]\begin{quote}
Hypertext is text displayed on a computer display or other electronic devices with references (hyperlinks) to other text that the reader can immediately access
\end{quote}\caption{Definition of hypertext from Wikipedia}\end{figure}

Other markup languages are not necessarily intended for immediate display.
Neither they are implied to have links.
Which is why I’m talking about hypertext and HTML in particular: links and metadata are built in.
All the HTML-related tooling has to support them.
And browsers, these glorified HTML viewers, are supposed to support a lot of legacy features (quirks).
Which all makes HTML both easier to write (look at the
\href{hypertext.h}{sources of this page)}
and reliable to view/transfer down the line.
Unlike most other plaintext markup/whatever formats.

\section*{Gemtext} \label{gemtext}

I’m interacting with a lot of Gemtext lately, and I can see its appeal.
It’s simple.
Focused.
Essentials only.

But it lacks a lot.
Overabuse of preformatted text elements is a standard practice.
There are no tables, images (not in the default package, at least), forms etc.
There’s no feedback loop with the user.
There are no established ways to transmit meta-information.

And, most importantly, Gemtext is a markup language, not a Hypertext format.
It’s not intended for interaction.
It’s not suitable for semantic knowledge webs.
So use Hypertext/Web Platform/HTML and live a happy life.

\par\noindent\rule{\textwidth}{0.4pt}
Copyright 2022-2025 Artyom Bologov (aartaka).
Any and all opinions listed here are my own and not representative of my employers; future, past and present.

\end{document}
