Splitting editorial out of the docs

Unknown — Sat, 13 Jun 2026 00:00:00 +0000

Reference documentation and editorial writing pull in opposite directions. The docs at docs.disarm.dev</a> exist to state exactly how disarm behaves: what a function returns, which Unicode ranges a transform touches, what a preset guarantees and what it does not. That writing should be precise, versioned, and boring in the way a reference is supposed to be boring.

Posts about why — design decisions, threat-model reasoning, benchmark write-ups, the occasional opinion about Unicode security — had started to crowd those pages. They answer a different question for a different reader, and they age differently. A reference page is either correct or it is a bug. A post is a snapshot of thinking at one point in time.

So the two now live apart. docs.disarm.dev stays the reference. This blog, at disarm.dev/blog, takes the editorial. Each can use the tooling that suits it: MkDocs for the API reference, a static generator for posts.

Next in the queue is the visual-versus-phonetic confusable mapping the landing page only summarizes, written out in full. Until then, here is the one line the whole project exists to make safe:

from</span> disarm</span> import</span> strip_obfuscation</span></span>
</span>
strip_obfuscation(</span>"рaypаl"</span>)</span>   # Cyrillic р, а  ->  "paypal"</span></span></code></pre>

disarm blog

Splitting editorial out of the docs