Markup Languages Compared: Markdown, AsciiDoc, reST, LaTeX, and More

Why the Choice Matters

At the simple end, any of these formats can represent headings, paragraphs, lists, links, and code blocks. The differences emerge at scale: a 2-page README versus a 400-page technical manual; a personal blog versus collaborative API docs with dozens of contributors; content that stays as HTML versus content that also needs to be PDF, EPUB, and DocBook.

Three questions determine most of the choice:

1. Who's writing it? Non-technical contributors need simpler syntax. Developers are fine with more structured formats.
2. What does it output? HTML only is easy. Multi-format output with consistent cross-references requires more capable formats.
3. What's the document length? Lightweight markup works well up to a few thousand words per file. Book-length content with chapters, indices, and cross-references demands a format that was designed for it.

Markdown (GFM and CommonMark)

Created by John Gruber in 2004 with the explicit goal of being readable as plain text. The original spec was intentionally loose, which led to a proliferation of incompatible implementations. CommonMark (2014) formalized the spec. GitHub Flavored Markdown (GFM) extends CommonMark with the features you actually need day-to-day.

Syntax

# Heading 1
## Heading 2

**bold** and *italic* and ~~strikethrough~~ (GFM)

- Unordered list item
- [ ] Task list item (GFM)
- [x] Completed task (GFM)

1. Ordered list
2. Second item

[Link text](https://toolsdock.com)
![Image alt](image.png "Optional title")

`inline code`

```javascript
// Fenced code block with language label
function hello() { return 'world'; }
```

| Header A | Header B |
|----------|----------|
| Cell 1   | Cell 2   |

> Blockquote

---  (horizontal rule)

The fragmentation problem

Despite CommonMark, "Markdown" still means different things in different contexts. Obsidian Markdown, Pandoc Markdown, MDX (Markdown + JSX), and GitHub Markdown all extend CommonMark differently. If you're writing for a specific platform, you're writing for that platform's flavor, not a universal standard.

Where Markdown genuinely falls short

• Cross-references: No native way to link to a section by its ID and have that link update if the heading text changes
• Admonitions: No standard syntax for warning/note/tip boxes—every tool invents its own extension
• Complex tables: Multi-line cells, column spans, and merged rows aren't possible in standard Markdown
• Document metadata: No native metadata syntax—YAML front matter is a common convention but not part of the spec
• Content reuse: No include mechanism for pulling in other files

Best for

README files, blog posts, single-page documentation, GitHub wikis, API quickstarts, note-taking, anything where the primary output is HTML and document length is under 10,000 words.

AsciiDoc

AsciiDoc was designed specifically to solve the things Markdown can't do at book scale. Stuart Rackham created it in 2002; Asciidoctor (the modern Ruby implementation) became the standard toolchain around 2013. O'Reilly adopted it as their primary authoring format. It's more verbose than Markdown but significantly more consistent and capable.

Syntax

= Document Title
Author Name 
:toc: left
:toc-depth: 2
:source-highlighter: rouge

== Section 1
=== Subsection

*bold*, _italic_, `inline code`, ^superscript^, ~subscript~

* Unordered item
** Nested item

. Ordered item
.. Nested ordered

https://toolsdock.com[Link text]

image::diagram.png[Diagram description, width=400]

[source,javascript]
----
function hello() {
  return 'world';
}
----

NOTE: This is an admonition (note).
WARNING: This is a warning admonition.
TIP: This is a tip.

|===
| Column A | Column B | Column C

| Cell 1
| Cell 2
| Cell 3

2+| Colspan (spans 2 columns)
| Normal cell
|===

<>

What AsciiDoc does better

• Consistency: One way to do each thing, clearly documented, unambiguous
• Cross-references: <> links resolve automatically; if you rename a section you update the ID, not every link
• Conditional content: Include or exclude sections based on attributes—publish different versions from one source
• Document includes: include::chapter1.adoc[] lets you split long documents into files
• Advanced tables: Column spans, row spans, cell-level formatting, nested content
• Multiple output formats: Asciidoctor generates HTML, PDF (via asciidoctor-pdf), EPUB, and DocBook from the same source
• Semantic roles: Attach custom CSS classes and roles to any block or inline element without leaving AsciiDoc syntax

Best for

Technical books, comprehensive API documentation, user manuals, content that needs consistent output across HTML, PDF, and EPUB, any documentation where the authors are technical.

reStructuredText (reST)

Part of Python's Docutils project, reST predates Markdown by a few years and was designed for Python documentation specifically. It powers the Sphinx documentation system that most major Python projects use. If you're documenting Python code, reST is the native language of your ecosystem.

Syntax

Document Title
==============

Section Heading
---------------

**bold**, *italic*, ``inline code``

- Unordered item
- Another item

#. Auto-numbered list
#. Second item

`Link text `_

.. image:: diagram.png
   :alt: Description
   :width: 400

.. code-block:: javascript

   function hello() {
     return 'world';
   }

.. note::
   This is a note admonition.

.. warning::
   This is a warning.

.. list-table:: Table Title
   :header-rows: 1

   * - Column A
     - Column B
   * - Cell 1
     - Cell 2

:ref:\`section-label\` links to a labeled section

The directive system

reST's main power comes from directives—the .. directive-name:: syntax that extends the format. Sphinx adds hundreds of directives for auto-documenting Python code, generating indices, creating domain-specific content, and much more. This is what makes reST genuinely extensible rather than just a different syntax for the same features.

Best for

Python project documentation, Sphinx-generated sites, API reference documentation with autodoc, anything that integrates with the Python documentation ecosystem.

LaTeX

LaTeX is the standard for academic and scientific publishing. Any paper with complex mathematics, any journal submission, any book with a bibliography managed by BibTeX—LaTeX is what the field uses. It's not a lightweight markup language; it's a full typesetting system with a programming-like macro language. The output quality is unmatched for print, but the learning curve is steep and the error messages are famously cryptic.

Syntax

\documentclass{article}
\usepackage{amsmath}
\usepackage{hyperref}

\title{Document Title}
\author{Author Name}
\date{\today}

\begin{document}
\maketitle
\tableofcontents

\section{Introduction}

\textbf{Bold}, \textit{italic}, \texttt{monospace}

Inline math: $E = mc^2$

Display math:
\begin{equation}
  \int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
\end{equation}

\begin{itemize}
  \item First item
  \item Second item
\end{itemize}

\href{https://toolsdock.com}{Link text}

\begin{tabular}{|l|c|r|}
\hline
Left & Center & Right \\
\hline
A & B & C \\
\hline
\end{tabular}

\cite{author2024}  % Citation
\bibliography{references}

\end{document}

Best for

Academic papers, journal submissions, theses, dissertations, books with complex mathematics, anything where typographic quality matters more than authoring speed.

HTML as a Markup Language

HTML is verbose for authoring but is what everything ultimately converts to. Writing HTML directly makes sense when you need precise control over the output, when you're embedding content in a web application, or when you're writing content-heavy static sites where the overhead of a conversion toolchain isn't worth it.

Modern HTML5 semantic elements (<article>, <section>, <aside>, <nav>) provide meaningful structure without requiring a separate markup language. With a sensible CSS framework and a template, writing HTML directly for a documentation site is practical. The main disadvantage is verbosity—HTML is significantly noisier than Markdown for the same content.

Best for

Web applications with document sections, static sites where you want direct CSS control, email templates, content that won't be converted to other formats.

Textile and Creole

Textile (2002) predates Markdown and was popular in Rails applications and Basecamp for years. Creole (2007) was an attempt to unify wiki markup syntaxes. Both are largely historical now—Markdown absorbed most of their use cases with better tool support.

# Textile
h1. Heading 1

*Bold* and _italic_ text

* Unordered list

"Link text":https://toolsdock.com

# Creole
= Heading 1 =

**Bold** and //italic// text

* Unordered list

[[https://toolsdock.com|Link text]]

If you're maintaining existing Textile content, it works fine. For new projects, choose Markdown unless you have a specific reason not to.

Org-mode

Org-mode is part of Emacs, and that context is essential to understanding it. Outside Emacs, it's a markup language. Inside Emacs, it's a productivity system: task management with TODO states, calendar integration, a spreadsheet engine in tables, literate programming (runnable code blocks that embed results), and export to many formats.

* Heading 1
** Heading 2
*** Heading 3

*Bold*, /italic/, =code=, ~verbatim~, +strikethrough+

- List item
  - Nested item

1. Ordered item
2. Second item

[[https://toolsdock.com][Link text]]

[[file:image.png][Image description]]

#+BEGIN_SRC javascript
function hello() { return 'world'; }
#+END_SRC

| Column A | Column B |
|----------+----------|
| Cell 1   | Cell 2   |

* TODO Task that needs doing
* DONE Completed task

If you're an Emacs user, Org-mode is worth learning—it's genuinely powerful for managing research, code, and documentation together. If you're not an Emacs user, the syntax works in other editors but you lose most of what makes Org-mode special.

Best for

Emacs users doing academic research, literate programming, personal knowledge management, or project planning with integrated task tracking.

Feature Comparison Table

Converting Between Formats with Pandoc

Pandoc converts between almost any pair of markup formats. It's indispensable for migration projects and for generating multiple output formats from a single source.

# Install
brew install pandoc          # macOS
sudo apt install pandoc      # Debian/Ubuntu
choco install pandoc         # Windows

# Basic conversions
pandoc input.md -o output.rst
pandoc input.rst -o output.html
pandoc input.adoc -f asciidoc -o output.html
pandoc input.md -o output.docx

# Markdown → reStructuredText
pandoc README.md -f gfm -t rst -o README.rst

# Markdown → AsciiDoc
pandoc README.md -f gfm -t asciidoc -o README.adoc

# Org-mode → Markdown
pandoc notes.org -f org -t gfm -o notes.md

# MediaWiki → Markdown
pandoc wiki.txt -f mediawiki -t gfm -o wiki.md

# Any markup → PDF (requires LaTeX or WeasyPrint)
pandoc input.md -o output.pdf

# With table of contents and syntax highlighting
pandoc guide.md -o guide.html --standalone --toc --highlight-style=github

What Pandoc doesn't convert well

Pandoc is exceptional for common features, but format-specific capabilities don't translate:

• AsciiDoc conditional blocks become static content—you lose the conditionality
• reST directives with no Markdown equivalent (like .. index::) are dropped
• Cross-references often convert to static text rather than functional links
• LaTeX custom macros are usually lost or incorrectly translated
• Complex table structures (spans, merged cells) may flatten to simple tables
• Org-mode TODO states and properties have no equivalent in most formats

After a Pandoc conversion, always review the output for broken cross-references, lost formatting, and format-specific features that didn't survive.

Migration strategy

1. Convert a representative sample (not everything) first
2. Identify which features didn't convert cleanly
3. Write a post-processing script for systematic issues (like cross-reference fixups)
4. Run the full conversion
5. Do a human review pass for edge cases
6. Test all links, code blocks, and tables in the output format

Choosing the Right Format

Conversion Tools