# From DITA XML to Markdown: lightweight information typing

<blockquote class="border-l-4 border-indigo-500 pl-4 py-2 my-6 bg-indigo-50/50 dark:bg-indigo-950/20 text-indigo-950 dark:text-indigo-200">
**Core premise:** Moving from DITA XML to Markdown is not an abandonment of structured information design. It is a migration of the **information-typing discipline** (concept, task, reference) from heavyweight XML schemas and proprietary toolchains into lightweight, open, docs-as-code workflows.
</blockquote>

<div class="my-6">

</div>

This blog has a history rooted in **DITA XML**. For years, it explored structured content management, sharing insights, tips, and reflections. Back then, DITA was the gold standard for large-scale technical documentation, but its complexity came at a cost: verbose XML syntax, specialized editors, and intricate publishing pipelines. Initially hosted on **WordPress**, the blog later moved to [**Sphinx**](https://www.sphinx-doc.org/) to experiment with alternatives like **reStructuredText**.

Today, the focus has shifted to **Markdown**.

Markdown is a **lightweight markup language**. Unlike XML, it’s human-readable, easy to write, and doesn’t require dedicated software. Yet it still allows technical writers to apply the **DITA philosophy of information typing**, structuring content into **concepts, tasks, and references**.

<figure class="my-6">
  ![DITA information typing: Staircase steps](https://redaction-technique.org/images/blog/dita-xml-to-markdown-lightweight-information-typing-large.webp)
  <figcaption class="text-sm text-gray-500 dark:text-slate-400 mt-2 text-center">Information typing as progressive steps: modular topics build clear, predictable pathways for users.</figcaption>
</figure>

## Architectural contrast: Heavy XML vs. Lightweight Markdown

Switching tools shifts where effort and complexity live:

<div class="grid grid-cols-1 md:grid-cols-2 gap-4 my-6">
  <ConceptCard title="Traditional DITA / XML Pipeline" subtitle="Rigid enforcement, heavy tooling">
    <ul class="space-y-1 text-sm">
      <li>• <strong>Syntax:</strong> Verbose XML tags, DTD/XSD schema validation</li>
      <li>• <strong>Authoring:</strong> Specialized XML editors (Oxygen, XMetaL)</li>
      <li>• <strong>Pipelines:</strong> Complex DITA Open Toolkit (DITA-OT) builds</li>
      <li>• <strong>Barrier:</strong> High operational cost and steep contributor friction</li>
    </ul>
  </ConceptCard>
  <ConceptCard title="Lightweight Markdown + Git Pipeline" subtitle="Wider participation, open ecosystem">
    <ul class="space-y-1 text-sm">
      <li>• <strong>Syntax:</strong> Clean, human-readable Markdown with frontmatter</li>
      <li>• <strong>Authoring:</strong> Any text editor (VS Code, Neovim, web editor)</li>
      <li>• <strong>Pipelines:</strong> Lightning-fast static site generators (Astro, Vite)</li>
      <li>• <strong>Barrier:</strong> Zero license cost, native Git collaboration, low friction</li>
    </ul>
  </ConceptCard>
</div>

<blockquote class="border-l-4 border-amber-500 pl-4 py-2 my-6 bg-amber-50/50 dark:bg-amber-950/20 text-amber-950 dark:text-amber-200">
**Discipline vs. Schema Enforcement:** DITA enforces its topic structure through strict DTD/XSD schema compilation—an invalid task without steps fails the build. Markdown does not inherently restrict what you type. To preserve strong typing without XML, teams rely on writer discipline, documentation style guides, and lightweight frontmatter validation or linting in CI.
</blockquote>

---

## The modern docs-as-code publishing pipeline

The diagram below illustrates how structured Markdown content flows through modern version control and static build engines directly to readers:

<div class="my-6">

</div>

---

## Evolution and continuity

This blog is a **work in progress**. Most [legacy content remains in French](https://docs.redaction-technique.org/), but **new content will primarily be in English**. Over time, older posts may be translated or curated to align with this new focus.

The mission remains the same: providing practical insights to help technical communicators navigate the evolving landscape of documentation, now with an emphasis on **lightweight, open, and sustainable practices**.

Stay tuned for posts, tutorials, and experiments at the intersection of **structured writing, lightweight markup, and modern documentation workflows**. You may also enjoy reading about [managing content in files instead of databases](https://redaction-technique.org/manage-content-in-files-not-databases), or the [journey from raw HTML editing to Git-based Markdown workflows](https://redaction-technique.org/web-journey-html-to-git-markdown).

---

## Related reading

- [Structured and unstructured formats](https://docs.redaction-technique.org/en/formats/structured-vs-unstructured-formats/) - the concept/task/reference model in depth.
- [Case studies in using DITA XML](https://docs.redaction-technique.org/en/formats/dita-xml-case-studies/) - real-world structured-authoring solutions.
- [Formats and tools](https://docs.redaction-technique.org/en/costs/formats-and-tools/) - why the format matters more than the tool.
- [Strong information typing without the XML overhead](https://redaction-technique.org/strong-information-typing-without-xml-overhead) - hands-on DITA-to-Markdown element mapping and task/concept templates.

## External sources

- [DITA and information typing](https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture)
- [Astro Starlight: lightweight docs alternative](https://starlight.astro.build/)
- [Markdown as the lightweight target](https://en.wikipedia.org/wiki/Markdown)

<small>*Hero image: ["ink jar and quills"](https://www.flickr.com/photos/84299143@N00/3922977291) by [Student of Rhythm](https://www.flickr.com/photos/84299143@N00/), licensed under [CC BY 2.0](https://creativecommons.org/licenses/by/2.0/).*</small>

---

Source: https://redaction-technique.org/dita-xml-to-markdown-lightweight-information-typing