I’ve used many content formats over the years, and while I love Markdown, I run into its limitations daily when I work on larger documentation projects.
In this issue, you’ll look at Markdown and explore why it might not be the best fit for technical content, and what else might work instead.
Markdown is everywhere. It’s human-readable, approachable, and has just enough syntax to make docs look good in GitHub or a static site. That ease of use is why it’s become the default choice for developer documentation. I’m using Markdown right now to write this newsletter issue. I love it.
But Markdown’s biggest advantage is its biggest drawback: it doesn’t describe the content like other formats can.
Think about how your content gets consumed. Your content isn’t just for human readers. Machines use it too. Your content gets indexed by search engines, and parsed by LLMs, and those things parse the well-formed HTML your systems publish. Markdown’s basic syntax only emits a small subset of the available semantic tags HTML allows.
IDE integrations can use your docs, too. And AI agents rely on structure to answer developer questions. If you’re only feeding them plain-text Markdown documents to reduce the number of tokens you send, you’re not providing as much context as you could.
Worse, when you want to reuse your content or syndicate content into another system, you quickly find out that Markdown is more of the lowest common denominator than a source of truth, as not all Markdown flavors are the same.
There are other options you can use that give you more control. But first, let’s look deeper into why you should move away from Markdown for serious work.
Markdown is “implicit typing” for content
If you’re a developer, you know all about type systems in programming languages. Some languages use Implicit typing, in which the compiler or interpreter infers the data type from the value. These languages give you flexibility, but no guarantees. That’s why many developers prefer languages that use explicit typing, where you predefine data types when writing the code. In those languages, the compiler doesn’t just build your code; it guarantees specific rules are followed. That’s the main reason for the rise of TypeScript over JavaScript: compile-time guarantees.
Markdown is implicit typing. It lets you write quickly, but without constraints or guarantees. There’s no schema. No way to enforce consistency. A heading in one file might be a concept, in another it might be a step, and there’s no machine-readable distinction between the two.
To complicate things further, there are multiple flavors of Markdown, each with its own features and markup. Here are just a few:
You think you’re writing “Markdown,” but what works in one tool may not render in another. Some Markdown processors allow footnotes, Others ignore soft line breaks. And some even require different formatting for code blocks. Inconsistency makes Markdown a shaky foundation for anything beyond the most basic document.
And then there’s MDX, which people often use to extend Markdown to support things it doesn’t:
Here’s a typical MDX snippet:
# Install
npm install my-library
That
It works beautifully on their site because their publishing system knows what
MDX shows that even in Markdown-centric ecosystems, people instinctively add more expressive markup. They know plain Markdown isn’t enough. They’re reinventing semantic markup, but in a way that’s custom, brittle, and not portable.
Why semantic markup matters
Semantic markup describes what content is, not just how it should look. It’s the difference between saying “here’s a bullet with some text” and “here’s a step in a procedure.” To a human, those may look the same on a page. To a machine or to a publishing pipeline, they are entirely different.
Web developers already went through all this with HTML. Prior to HTML5, you had
,
,
, and many other elements that described the content.
Semantic markup matters for two important and related reasons:
- Transformation and reuse. With semantic markup, you can publish the same content to HTML, PDF, ePub, or even plain Markdown. With Markdown as your source, you can't easily go to another format. You can't turn a bullet into a
- Machine consumption. LLMs and agents can make better use of content that carries structure. A step marked as a
Let's explore four formats that give you more control over structure than plain Markdown.
reStructuredText
reStructuredText is a plain-text markup language from the Python/Docutils ecosystem that supports directives, roles, and structural semantics. It is the foundational format used by Sphinx for generating documentation.
Installation
============
.. code-block:: bash
npm install my-library
.. note::
This library requires Node.JS ≥ 22.
See also :ref:`usage-guide`.
Here you see a code-block directive, an admonition (note), and an explicit cross-reference via :ref:. You'll find support for images, figures, topics, sidebars, pull quotes, epigraphs, and citations as well.
All of those encode semantics, not just presentation.
AsciiDoc
AsciiDoc aims to be human-readable but semantically expressive. It has attributes, conditional content, include mechanisms, and more.
Here's an example of AsciiDoc:
= Installation
:revnumber: 1.2
:platform: linux
:prev_section: introduction
:next_section: create-project
[source,bash]
----
npm install my-library
----
NOTE: This library requires Node.JS ≥ 22.
See > for examples.
AsciiDoc has native support for document front-matter. Attributes like :revnumber: or :platform: let you parameterize content.
> is a cross-reference syntax.
Like reStructuredText, AsciiDoc supports admonitions like NOTE and WARNING so you don't have to build your own custom renderer. It also has support for sidebars, and you can add line highlighting and callouts to your code blocks without additional extensions.
And if you're writing technical documentation, there's explicit support for marking up UI elements and keyboard shortcuts.
Using AsciiDoctor, you can transform AsciiDoc into other formats, including HTML, PDF, ePub, and DocBook, which you'll look at next.
DocBook (XML)
DocBook is an XML-based document model explicitly designed for technical publishing. It expresses hierarchical and semantic structure in tags and attributes, enabling industrial-grade transformations.
Here's an example
id="install-library">
linkend="usage-chapter">Usage Guide
Every tag is meaningful:
DocBook's rich ecosystem of XSLT stylesheets supports transforming to HTML, PDF, man pages, and even Markdown. Using DocBook ensures structure and validation at scale, as long as you use the tags it provides.
Then there's DITA.
DITA (Darwin Information Typing Architecture)
DITA is a standard for writing, managing, and publishing content. It's a topic-based XML architecture with built-in reuse, specialization, and modular content design. It's an open standard, and it's widely used in enterprises for multi-channel, structured content that needs standardization and reuse.
Here's an example:
id="install">
DITA defines types like
One of the more interesting features DITA provides is the ability to filter content and create multiple versions from a single document.
The DITA Open Toolkit and many enterprise tools handle rendering, transformation, and reuse pipelines.
Ew. XML.
Yes, XML. The syntax is more verbose than Markdown. Tooling is less ubiquitous than Markdown. Migration requires effort, and your team may resist the learning curve. For small docs, Markdown's features are often enough.
But if you're already bolting semantics onto Markdown with MDX or plugins or custom scripts, you're paying that complexity cost anyway, and you don't get the benefits of standardization or portability. You're building a fragile, custom semantic layer instead of adopting one that already works.
So where does that leave you?
If you're writing a quick README or a short-lived doc, Markdown is fine. It's fast, approachable, and does the job. If you're building a developer documentation site that needs some structure, reStructuredText or AsciiDoc are better choices. They balance expressiveness with usability. And if you're managing a large doc set that needs syndication, reuse, and multi-channel publishing, DocBook and DITA give you the semantics and tooling to make that process more manageable.
The key is to start with the richest format you can manage and export downward. Markdown makes a great output for developers. It's approachable and familiar. But be careful not to lock yourself into it as your source of truth, because you can't add context back as easily as you can strip it out.
- I have a new book out. Check out Write Better with Vale. This book walks you through implementing Vale, the prose linter, on your next writing project to create consistent, quality content.
- Tidewave.ai is a full-stack coding agent from the creators of the Elixir programming language. It supports Ruby on Rails, Phoenix, and React applications and has a free tier. You'll need an API key for OpenAI, Anthropic, or GitHub Copilot to use it.
- Google's Chrome for Developers blog has a post on creating accessible carousels. It's worth the read if you have to implement one of these on your site.
Before the next issue, here are a couple of things you should try to get some hands-on experience with a different format.
As always, thanks for reading. Share this issue with someone who you think would find this helpful.
I'd love to talk with you about this issue on BlueSky, Mastodon, Twitter, or LinkedIn. Let's connect!
Please support this newsletter and my work by encouraging others to subscribe and by buying a friend a copy of Write Better with Vale, tmux 3, Exercises for Programmers, Small, Sharp Software Tools, or any of my other books.
