How DITA Compares

See how the DITA language stacks up against HTML5, Markdown, AsciiDoc, reStructuredText, and DocBook.

Every one of these formats can produce readable content. They differ in how much structure, reuse, and publishing automation they give you once your content grows beyond a handful of pages.

	DITA	HTML5	Markdown	AsciiDoc	reStructuredText	DocBook
Format	XML vocabulary	Markup language	Plain text, lightweight markup	Plain text, lightweight markup	Plain text, lightweight markup	XML vocabulary
Primary role	Authoring format	Output format	Authoring format	Authoring format	Authoring format	Authoring format
Content model	Topic-based (concept, task, reference, troubleshooting), enforced by schema	Document-based, freeform	Document-based, freeform	Document-based, freeform with semantic blocks	Document-based, freeform with directives	Document-based (books, chapters, sections), enforced by schema
Content reuse	Content references (conref/keyref), maps for assembly	None built in	None built in	Includes and attributes	Includes and substitutions	XInclude and cross-references
Conditional publishing	Built-in filtering and flagging (DITAVAL)	None built in	None built in	Conditional attributes (tool-dependent)	Tags (tool-dependent)	Built-in profiling attributes (condition, os, arch)
Extensibility	Formal specialization of elements and attributes	Custom elements via separate specs	Flavors and extensions (tool-dependent)	Custom blocks and macros	Custom directives and roles	Customization layers (schema-based)
Typical output	HTML, PDF, EPUB, help systems, mobile, print—via one source	Web pages (the destination, not a source format)	HTML, sometimes PDF	HTML, PDF, EPUB, slides, man pages	HTML, PDF, EPUB (commonly via Sphinx)	HTML, PDF, EPUB, man pages
Governed by	OASIS DITA Technical Committee	WHATWG / W3C	No formal standard (CommonMark is the closest)	Eclipse Foundation AsciiDoc Language project	Docutils project	Hosted by OASIS; Technical Committee closed in 2024

DITA vs. Markdown

Markdown’s appeal is its simplicity: a handful of characters produce headings, lists, and links. That makes it ideal for READMEs, changelogs, and short-lived content. It has no standard mechanism for content reuse, conditional text, or semantic topic types, so large documentation sets built in Markdown tend to accumulate inconsistency as they grow. DITA addresses that gap directly, with content references and topic types built into the language. Through Lightweight DITA, the MDITA format lets writers use familiar Markdown syntax while still producing standard DITA content.

index.md

# Topic Title

A brief description of topic with **bold** and _italic_ text.

A link to [Eclipse®](https://eclipse.org).
A reusable link to [GitLab](gitlab).

![An image](an-image.png)

- Unordered list item
  - Nest items by aligning marker with text of parent item
- Another unordered list item

**TIP:** An admonition can be emulated using a bold label.

## Subsection title

A code block with a Ruby function named `hello` that prints
“Hello, World!”:

```ruby
def hello name = 'World'
  puts "Hello, #{name}!"
end
```

[gitlab]: https://about.gitlab.com/

index.dita

book.ditamap

<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="required_id">
  <title>Topic Title</title>
  <shortdesc>A brief description of topic with <b>bold</b> and
      <i>italic</i> text.</shortdesc>
  <body>
    <p>An external link to <xref href="https://eclipse.org"
        scope="external" format="html"><tm tmtype="reg"
        >Eclipse</tm></xref>. A reusable link to <xref keyref="gitlab"
      />.</p>
    <fig>
      <title>Image title</title>
      <image href="an-image.jpg" alt="An image"/>
    </fig>
    <ul>
      <li>Unordered list item <ul>
          <li>Nest a another list to make a nested item</li>
        </ul>
      </li>
      <li>Another unordered list item</li>
    </ul>
    <note type="tip">One of 13 built-in admonition block types.</note>
    <example>
      <title>Subsection title</title>
      <p>The following source code block contains a Ruby function named
          <apiname>hello</apiname> that prints <systemoutput>Hello,
          World!</systemoutput>.</p>
      <codeblock outputclass="language-ruby">def hello name = 'World'
  puts "Hello, #{name}!"
end</codeblock>
    </example>
  </body>
</topic>

<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
  <title>Book Title</title>
  <keydef keys="gitlab" href="https://about.gitlab.com/"
          scope="external" format="html"/>
  <topicref href="index.dita"/>
</map>

DITA vs. HTML5

HTML5 is the language browsers render, not one people typically author large documentation sets in directly. It has no native concept of topics, content reuse, or conditional publishing. Those concerns are usually bolted on with a separate content management system. With DITA, HTML5 is simply one of several outputs a publishing engine can generate from a single set of source topics. That means no second authoring effort is needed to also produce PDF, EPUB, or other formats.

index.html

<!doctype html>
<html lang="en">
<head>
  <title>Topic Title</title>
</head>
<body>
<h1>Document Title</h1>
<p>A brief description of topic with <strong>bold</strong> and
  <em>italic</em> text.</p>
<p>A link to <a href="https://eclipse.org">Eclipse&reg;</a>.</p>
<figure>
  <figcaption>Image title</figcaption>
  <img src="an-image.jpg" alt="An image">
</figure>
<ul>
  <li>Unordered list item
    <ul>
      <li>Nest a another list to make a nested item</li>
    </ul>
  </li>
  <li>Another unordered list item</li>
</ul>
<div class="admonition note">
  <span class="label">TIP</span>
  <div class="content">
    <p>An admonition can be emulated using CSS.</p>
  </div>
</div>
<section>
  <h2>Section Title</h2>
  <p>
    A code block with a Python function named <code>hello</code> that
    prints <q>Hello, World</q>:
  </p>
  <pre class="language-ruby">def hello name = 'World'
  puts "Hello, #{name}!"
end</pre>
</section>
</body>
</html>

index.dita

book.ditamap

<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="required_id">
  <title>Topic Title</title>
  <shortdesc>A brief description of topic with <b>bold</b> and
      <i>italic</i> text.</shortdesc>
  <body>
    <p>An external link to <xref href="https://eclipse.org"
        scope="external" format="html"><tm tmtype="reg"
        >Eclipse</tm></xref>. A reusable link to <xref keyref="gitlab"
      />.</p>
    <fig>
      <title>Image title</title>
      <image href="an-image.jpg" alt="An image"/>
    </fig>
    <ul>
      <li>Unordered list item <ul>
          <li>Nest a another list to make a nested item</li>
        </ul>
      </li>
      <li>Another unordered list item</li>
    </ul>
    <note type="tip">One of 13 built-in admonition block types.</note>
    <example>
      <title>Subsection title</title>
      <p>The following source code block contains a Ruby function named
          <apiname>hello</apiname> that prints <systemoutput>Hello,
          World!</systemoutput>.</p>
      <codeblock outputclass="language-ruby">def hello name = 'World'
  puts "Hello, #{name}!"
end</codeblock>
    </example>
  </body>
</topic>

<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
  <title>Book Title</title>
  <keydef keys="gitlab" href="https://about.gitlab.com/"
          scope="external" format="html"/>
  <topicref href="index.dita"/>
</map>

DITA vs. AsciiDoc

AsciiDoc is a plain-text format with includes, attributes, and semantic blocks. Those features support meaningful content reuse and conditional text without leaving plain text. DITA takes a different approach: formal, schema-validated topic types and a map structure assemble content from many independent files. That trade-off—more upfront structure for machine-enforced consistency—tends to matter most for large, multi-author, multi-product documentation sets.

index.adoc

book.adoc

= Topic Title

A brief description of topic with *bold* and _deleted_ text.

An external link to https://eclipse.org[Eclipse(R)].
A reusable link to {gitlab}[GitLab].

image::an-image.png[An image]

* Unordered list item
** Add another marker to make a nested item
* Another unordered list item

TIP: One of five built-in admonition block types.

== Subsection title

The following source code block contains a Ruby function named `hello`
that prints "`Hello, World!`".

[,ruby]
----
def hello name = 'World'
  puts "Hello, #{name}!"
end
----

= Book Title
:doctype: book
:gitlab: https://about.gitlab.com/

include::index.adoc[leveloffset=1]

index.dita

book.ditamap

<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="required_id">
  <title>Topic Title</title>
  <shortdesc>A brief description of topic with <b>bold</b> and
      <i>italic</i> text.</shortdesc>
  <body>
    <p>An external link to <xref href="https://eclipse.org"
        scope="external" format="html"><tm tmtype="reg"
        >Eclipse</tm></xref>. A reusable link to <xref keyref="gitlab"
      />.</p>
    <fig>
      <title>Image title</title>
      <image href="an-image.jpg" alt="An image"/>
    </fig>
    <ul>
      <li>Unordered list item <ul>
          <li>Nest a another list to make a nested item</li>
        </ul>
      </li>
      <li>Another unordered list item</li>
    </ul>
    <note type="tip">One of 13 built-in admonition block types.</note>
    <example>
      <title>Subsection title</title>
      <p>The following source code block contains a Ruby function named
          <apiname>hello</apiname> that prints <systemoutput>Hello,
          World!</systemoutput>.</p>
      <codeblock outputclass="language-ruby">def hello name = 'World'
  puts "Hello, #{name}!"
end</codeblock>
    </example>
  </body>
</topic>

<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
  <title>Book Title</title>
  <keydef keys="gitlab" href="https://about.gitlab.com/"
          scope="external" format="html"/>
  <topicref href="index.dita"/>
</map>

DITA vs. reStructuredText

reStructuredText, especially paired with Sphinx, is a strong choice for documenting a single codebase or project. Directives and roles support structured, cross-referenced technical writing. DITA is built for a broader scope, assembling and reusing topics across many products, releases, and organizations through maps. Formal specialization lets teams extend the vocabulary for their domain while staying interoperable with standard DITA tools. Where reStructuredText is closely tied to its surrounding tool ecosystem, DITA’s processing model is defined independently of any single publishing engine.

index.rst

book.rst

Document Title
**************

A brief description of topic with **bold** and *italic* text.

An external link to `Eclipse |reg| <https://eclipse.org>`_.
A reusable link to `GitLab`_.

.. image:: /images/an-image.png
   :alt: An image

* Unordered list item

  * Nest items by aligning marker with text of parent item

* Another unordered list item

.. tip:: One of nine supported admonition block types.

Subsection title
----------------

The following source code block contains a Ruby function named ``hello``
that prints "Hello, World!".

.. code-block:: ruby

   def hello name = 'World'
     puts "Hello, #{name}!"
   end

.. _GitLab: https://about.gitlab.com/
.. |reg| unicode:: U+00AE

.. include:: index.rst

index.dita

book.ditamap

<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="required_id">
  <title>Topic Title</title>
  <shortdesc>A brief description of topic with <b>bold</b> and
      <i>italic</i> text.</shortdesc>
  <body>
    <p>An external link to <xref href="https://eclipse.org"
        scope="external" format="html"><tm tmtype="reg"
        >Eclipse</tm></xref>. A reusable link to <xref keyref="gitlab"
      />.</p>
    <fig>
      <title>Image title</title>
      <image href="an-image.jpg" alt="An image"/>
    </fig>
    <ul>
      <li>Unordered list item <ul>
          <li>Nest a another list to make a nested item</li>
        </ul>
      </li>
      <li>Another unordered list item</li>
    </ul>
    <note type="tip">One of 13 built-in admonition block types.</note>
    <example>
      <title>Subsection title</title>
      <p>The following source code block contains a Ruby function named
          <apiname>hello</apiname> that prints <systemoutput>Hello,
          World!</systemoutput>.</p>
      <codeblock outputclass="language-ruby">def hello name = 'World'
  puts "Hello, #{name}!"
end</codeblock>
    </example>
  </body>
</topic>

<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
  <title>Book Title</title>
  <keydef keys="gitlab" href="https://about.gitlab.com/"
          scope="external" format="html"/>
  <topicref href="index.dita"/>
</map>

DITA vs. DocBook

DocBook is also a mature XML vocabulary, used for software documentation, books, and Linux distribution manuals. It supports modularization through mechanisms like XInclude. It was developed under OASIS, but its Technical Committee closed in 2024, so it’s no longer under active development. Where DocBook centers on document structures—books, chapters, and prefaces—DITA centers on independent topics assembled through maps. Depending on whether your content is closer to a single authored volume or spans many products, either structure can be a good fit.

index.xml

book.xml

<?xml-model href="http://docbook.org/xml/5.2/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
<chapter xmlns="http://docbook.org/ns/docbook"
  xmlns:xl="http://www.w3.org/1999/xlink" xml:id="_chapter_title"
  version="5.2">
  <title>Topic Title</title>
  <simpara>A paragraph with <emphasis role="strong">bold</emphasis> and
      <emphasis>italic</emphasis> text.</simpara>
  <figure>
    <title>Image title</title>
    <mediaobject>
      <imageobject>
        <imagedata fileref="an-image.jpg" align="center"/>
      </imageobject>
      <textobject>
        <phrase>An image</phrase>
      </textobject>
    </mediaobject>
  </figure>
  <simpara> The <literal>&lt;link&gt;</literal> tag is used for
    source-to-source links, like <link xl:href="a-book.xml">a
    book</link>, and external links, like <trademark class="registered"
        ><link xl:href="https://eclipse.org">Eclipse</link></trademark>. </simpara>
  <tip>
    <simpara>One of five built-in admonition block types.</simpara>
  </tip>
  <section>
    <title>Subsection title</title>
    <simpara> The following program listing contains a Ruby function
      named <literal>hello</literal> that prints <quote role="double"
        >Hello, World!</quote>. </simpara>
    <programlisting language="ruby">def hello name = 'World'
  puts "Hello, #{name}!"
end</programlisting>
  </section>
</chapter>

<book xmlns="http://docbook.org/ns/docbook"
  xmlns:xi="http://www.w3.org/2001/XInclude" version="5.2">
  <title>Book Title</title>
  <xi:include href="index.xml"/>
</book>

index.dita

book.ditamap

<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="required_id">
  <title>Topic Title</title>
  <shortdesc>A brief description of topic with <b>bold</b> and
      <i>italic</i> text.</shortdesc>
  <body>
    <p>An external link to <xref href="https://eclipse.org"
        scope="external" format="html"><tm tmtype="reg"
        >Eclipse</tm></xref>. A reusable link to <xref keyref="gitlab"
      />.</p>
    <fig>
      <title>Image title</title>
      <image href="an-image.jpg" alt="An image"/>
    </fig>
    <ul>
      <li>Unordered list item <ul>
          <li>Nest a another list to make a nested item</li>
        </ul>
      </li>
      <li>Another unordered list item</li>
    </ul>
    <note type="tip">One of 13 built-in admonition block types.</note>
    <example>
      <title>Subsection title</title>
      <p>The following source code block contains a Ruby function named
          <apiname>hello</apiname> that prints <systemoutput>Hello,
          World!</systemoutput>.</p>
      <codeblock outputclass="language-ruby">def hello name = 'World'
  puts "Hello, #{name}!"
end</codeblock>
    </example>
  </body>
</topic>

<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
  <title>Book Title</title>
  <keydef keys="gitlab" href="https://about.gitlab.com/"
          scope="external" format="html"/>
  <topicref href="index.dita"/>
</map>

Choosing the Right Format

There’s no single correct answer for every project. Lightweight, single-document formats like Markdown, AsciiDoc, and reStructuredText are often the fastest way to get a small project documented well. DITA’s more complex features pay off when content needs to be reused across products, translated into multiple languages, filtered for different audiences, or published to several formats from one source—the scenarios technical documentation teams hit as they scale.