From DITA XML to Markdown: lightweight information typing

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.

1. DITA XML (Strict schemas, heavy toolchains, high overhead)
↓ →
2. Core information typing (Concept, Task, Reference discipline)
↓ →
3. Markdown authoring (Plain text, universal tooling, zero lock-in)
↓ →
4. Git review & CI/CD (Pull requests, automated checks, versioning)
↓ →
5. Astro & static publishing (Instant builds, modern web docs)

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 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.

DITA information typing: Staircase steps — Information typing as progressive steps: modular topics build clear, predictable pathways for users.

Preserving the core triad: Concept, Task, Reference

The genius of DITA was never its angle brackets—it was teaching technical communicators to categorize content by user intent. That cognitive discipline translates seamlessly into plain text:

1. Concept

Understanding & Context

Answers what is this and why? Explanatory background, system architecture, and mental models without procedural action steps.

2. Task

Procedures & Outcomes

Answers how do I accomplish this? Goal-oriented ordered instructions with clear prerequisites, commands, and expected results.

3. Reference

Specifications & Facts

Answers what are the exact parameters? Structured lookup material, API parameters, tables, and configuration settings for rapid scanning.

Instead of relying on heavy XML toolchains, writers can leverage open, freely available tools (static site generators like Astro and its Starlight theme, among others). Structured documentation is now accessible to a wider audience: individual writers, small teams, open-source contributors, and enterprise documentation teams alike. For a deeper look at how to apply DITA’s information typing discipline in Markdown, see strong information typing without the XML overhead.

Architectural contrast: Heavy XML vs. Lightweight Markdown

Switching tools shifts where effort and complexity live:

Traditional DITA / XML Pipeline

Rigid enforcement, heavy tooling

• Syntax: Verbose XML tags, DTD/XSD schema validation
• Authoring: Specialized XML editors (Oxygen, XMetaL)
• Pipelines: Complex DITA Open Toolkit (DITA-OT) builds
• Barrier: High operational cost and steep contributor friction

Lightweight Markdown + Git Pipeline

Wider participation, open ecosystem

• Syntax: Clean, human-readable Markdown with frontmatter
• Authoring: Any text editor (VS Code, Neovim, web editor)
• Pipelines: Lightning-fast static site generators (Astro, Vite)
• Barrier: Zero license cost, native Git collaboration, low friction

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.

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:

1. Write (Modular Markdown content structured by intent)
↓ →
2. GitHub review (Pull requests, automated linting, peer feedback)
↓ →
3. Astro build (Fast static compilation & component rendering)
↓ →
4. CDN distribution (Edge caching & global content delivery)
↓ →
5. Published web (Responsive, accessible, lightning-fast documentation)

Figure 1 — DITA to Markdown migration pipeline: structural parsing, metadata preservation, and static site compilation.

Evolution and continuity

This blog is a work in progress. Most legacy content remains in French, 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, or the journey from raw HTML editing to Git-based Markdown workflows.

Structured and unstructured formats — the concept/task/reference model in depth.
Case studies in using DITA XML — real-world structured-authoring solutions.
Formats and tools — why the format matters more than the tool.
Strong information typing without the XML overhead — hands-on DITA-to-Markdown element mapping and task/concept templates.

External sources

Hero image: “ink jar and quills” by Student of Rhythm, licensed under CC BY 2.0.