Markdown vs AsciiDoc vs reStructuredText: Picking Plain Text
Quick answer
Markdown wins on simplicity. It's the right default for notes, READMEs, and blog posts. AsciiDoc and reStructuredText trade that simplicity for native tables, admonitions, cross-references, and one-source-to-many-formats output — which is why they show up in long-form technical documentation instead.
That trade-off isn't accidental. Markdown was designed to be "as easy-to-read and easy-to-write as is feasible" — a writing format for prose, not a replacement for HTML. AsciiDoc and reStructuredText start from a different premise: give the author more structure up front in exchange for output they don't have to build by hand. Neither approach is wrong; they're just built for different jobs. And if you're weighing plain text against something heavier in the first place, here's why writers choose plain text at all.
What follows: the syntax differences, what each format hands you natively, and when the extra power is actually worth learning.
How it actually works
Syntax side by side
All three formats agree on one thing — you're still typing plain text. Past that, they diverge fast.
Markdown keeps headings and links close to how you'd write them by hand:
# A heading
[link text](https://example.com)AsciiDoc asks for a bit more structure. Headings use = signs, and links put the URL first:
= A heading
https://example.com[link text]reStructuredText goes further still. Headings get underlined with a repeated punctuation character, and there's no fixed rule for which character maps to which level — the hierarchy is inferred from the order headings appear in the document:
A heading
=========
`link text <https://example.com>`_That underline-punctuation approach is reStructuredText's steepest learning curve. Two documents can use completely different underline characters for the same heading depth, so you can't tell which level you're looking at without reading the rest of the file.
What's native vs. bolted on
AsciiDoc ships admonitions, tables with customizable alignment and borders, cross-references, and an automatic table of contents as built-in syntax — no plugin required. It also has a genuine attributes system: named or positional variables you can reuse across a document.
reStructuredText covers similar ground through directives — generic blocks starting with `..` that handle admonitions, image embeds, tables, and code blocks. Sphinx layers its own cross-referencing roles on top for linking between pages.
Markdown, by design, doesn't try to do any of that natively. Need a table of contents or a callout box? You're reaching for a plugin, a static-site-generator extension, or raw HTML in the file — the direct cost of Markdown's original scope decision to stay a writing format, not a publishing one. It's also why the same Markdown file can render differently depending on which parser opens it. AsciiDoc and reStructuredText each standardized on one implementation early, so that particular headache mostly doesn't exist for them.
Where each one actually lives
AsciiDoc has been a single Eclipse Foundation standard since 2019. It shows up in Git's own project documentation, O'Reilly Media books, and Red Hat's product docs — places that need one source file to become HTML, a PDF, and a man page without rewriting anything.
reStructuredText has been part of the Docutils project since 2001 and a core piece of Sphinx since 2008. That's the backbone of the official Python documentation and projects like the Linux kernel, CMake, and LLVM — anywhere docs get generated straight from source-code comments.
Markdown, meanwhile, is everywhere READMEs and blogs are, without a single formal standard behind it. CommonMark and GitHub Flavored Markdown (GFM) exist specifically to patch the gaps its many early implementations left behind.
When to use it (and when to skip it)
Reach for AsciiDoc or reStructuredText when you're writing long-form technical documentation, a book, or anything that needs to compile from one source into HTML, PDF, EPUB, or a man page. That's the exact case both formats were built to handle — and where Markdown will fight you the whole way.
Reach for reStructuredText specifically when your docs are generated from Python docstrings through Sphinx. That pipeline is the entire reason the format has the adoption it does; outside that ecosystem, there's rarely a reason to pick reST over AsciiDoc.
Stick with Markdown for notes, drafts, READMEs, and anything you write to be read as plain text first. AsciiDoc and reStructuredText's native tables, admonitions, and attributes are real capabilities, sure, but they're also more syntax to hold in your head while writing — a trade that doesn't pay off for a quick how-to. Producing longer technical docs in Markdown anyway? This style guide covers keeping them consistent without switching formats.
Be honest about the ceiling: Markdown genuinely can't do complex cross-references or attribute-driven templating without extra tooling. That's not a flaw to work around. It's the format doing what it was designed to do.
How Carets fits in
If you're mostly writing notes, drafts, and READMEs rather than a multi-format documentation set, Markdown is the format that fits — and Carets is built around it. Every file is Markdown and plain text, with syntax highlighting for the code you drop in alongside it, so a heading, a fenced code block, or a task list looks right without a preview pane getting in the way.
Files, projects, and tags keep a growing set of Markdown notes organized without you inventing your own folder system. And because everything stays plain text, it's portable: the same file opens anywhere, years from now, with no proprietary format standing between you and your own writing.
Get Carets on iPhone, iPad, and Mac.
Frequently Asked Questions
Is AsciiDoc harder to learn than Markdown?
Its syntax asks more of you up front — headings use = signs and links take a url[text] form — but most of that complexity buys native tables, admonitions, and cross-references that Markdown either can't do or needs a plugin or raw HTML for. For a quick note, Markdown's still faster to write.
Why does Python documentation use reStructuredText instead of Markdown?
reStructuredText has been part of the Docutils project since 2001 and a core piece of Sphinx since 2008, which generates docs directly from Python docstrings. It's the tooling, not just the syntax, that made the Python ecosystem standardize on it.
Can AsciiDoc or reStructuredText output more than HTML?
Yes. AsciiDoc compiles the same source file to HTML, PDF, EPUB3, DocBook, and man pages. reStructuredText gets similar reach through Sphinx, which builds HTML, PDF, and more from the same .rst sources. Markdown is HTML-first by default, so PDF and other formats usually mean an extra conversion step.
Why did Markdown end up with so many incompatible flavors?
Gruber's original 2004 spec left gaps — no native tables, no fenced code blocks — so implementations filled them in differently. CommonMark and GitHub Flavored Markdown (GFM) exist specifically to patch that fragmentation for the web and developer-docs use case Markdown is actually used for day to day.
Should I switch my notes from Markdown to AsciiDoc or reStructuredText?
Usually, no. Both alternatives earn their complexity in long-form technical documentation or Python-project doc generation — not in day-to-day notes, drafts, or READMEs, where Markdown's minimal syntax is the point, not a limitation.
Conclusion
Markdown, AsciiDoc, and reStructuredText all keep your writing in plain text, but they're solving different problems. Markdown stays minimal on purpose — a writing format, not a publishing one — which is exactly right for notes, READMEs, and blog posts. AsciiDoc and reStructuredText add native structure and multi-format output for the cases where long-form technical documentation actually needs it.
Most writers and developers never need to leave Markdown. It's worth knowing AsciiDoc and reStructuredText exist for the day a project's documentation genuinely outgrows it — and worth not reaching for them before then.