Strong information typing without the XML overhead

If you’ve spent years working daily with the DITA XML platform, you know that DITA is more than a markup language. It’s a way of thinking about information design. Writing tasks, concepts, and references in DITA teaches you to break down content into consistent building blocks, which makes documentation easier to navigate, maintain, and reuse.

XML overhead: A cargo ship

The good news is: you don’t need an XML editor or a DITA-OT pipeline to keep practicing those principles. With Markdown and modern docs-as-code workflows, you can implement DITA’s information typing philosophy in a lightweight, flexible way.

The DITA mindset

DITA trains you to ask:

Is this a task? → A sequence of steps that helps the reader achieve a goal.
Is this a concept? → A piece of explanatory content that builds understanding.
Is this a reference? → A structured lookup table or fact sheet.

Once you’ve internalized this mindset, it becomes natural to apply it even outside XML. Markdown pages, Git-based workflows, and static site generators all benefit when you keep these categories clear.

DITA-like task pages

DITA task topics have strict rules: short context, prerequisites, ordered steps, results. The official OASIS example is as follows:

DITA Task Example

<task id="sqlj">
<title>Creating an SQLJ file</title>
<taskbody>
<context>Once you have set up SQLJ, you need to create a new SQLJ file.</context>
<steps>
<step>
 <cmd>Select <menucascade><uicontrol>File</uicontrol>
 <uicontrol>New</uicontrol></menucascade>.</cmd>
 <info>New files are created with default values based on a standard template.</info>
</step>
</steps>
</taskbody>
</task>

graph LR %% Nodes T[Task Topic] T1[Title] T2[Short Description] T3[Prerequisites] T4[Steps] T5[Result / Output] T6[Example / Notes] %% Nested steps S1[Step 1] S1a[Command] S1b[Additional info] S1c[Step result] S2[Step 2] S2a[Command] S2b[Additional info] S2c[Step result] %% Structure T --> T1 T --> T2 T --> T3 T --> T4 T --> T5 T --> T6 T4 --> S1 T4 --> S2 S1 --> S1a S1 --> S1b S1 --> S1c S2 --> S2a S2 --> S2b S2 --> S2c %% Styling classDef topic fill:#fbe9e4,stroke:#experimental-astro-api-docsdf9277,stroke-width:2px,color:#5a2e23,font-weight:bold,rx:8,ry:8; classDef step fill:#f6d1c5,stroke:#d97d61,stroke-width:2px,color:#4a241a,font-weight:bold,rx:8,ry:8; classDef substep fill:#efb9a6,stroke:#c96a52,stroke-width:2px,color:#3d1d15,font-weight:bold,rx:8,ry:8; class T topic class T1,T2,T3,T4,T5,T6 step class S1,S1a,S1b,S1c,S2,S2a,S2b,S2c substep linkStyle default stroke:#df9277,stroke-width:2px;

Hierarchy of Elements in a DITA Task Topic (Steps, Commands, Information, and Metadata)

You can recreate this in Markdown easily:

# Creating an SQLJ file

Once you have set up SQLJ, you need to create a new SQLJ file.

1. Select **File** > **New**

   New files are created with default values based on a standard template.

This keeps the procedural content focused and predictable, just like in DITA.

DITA-like concept pages

Concepts explain “what” and “why” rather than “how.” The official OASIS example is as follows:

<concept id="concept">
 <title>Introduction to Bird Calling</title>
 <shortdesc>If you wish to attract more birds to your Acme Bird Feeder,
learn the art of bird calling. Bird calling is an efficient way
to alert more birds to the presence of your bird feeder.</shortdesc>
 <conbody>
   <p>Bird calling requires learning:</p>
   <ul>
    <li>Popular and classical bird songs</li>
    <li>How to whistle like a bird</li>
   </ul>
 </conbody>
</concept>

In Markdown, you can still signal that you’re writing a concept by structuring around definition and explanation.

# Introduction to Bird Calling

If you wish to attract more birds to your Acme Bird Feeder, learn the art of
bird calling. Bird calling is an efficient way to alert more birds to the
presence of your bird feeder.

Bird calling requires learning:

- Popular and classical bird songs
- How to whistle like a bird

The structure shows it’s an explanatory page, not a step-by-step guide.

Why this matters

DITA XML can feel heavy to implement in modern docs pipelines. But the discipline you develop with years of daily practice doesn’t vanish when you move to Markdown. Instead, it becomes a superpower.

By bringing DITA’s principles into lightweight environments, you:

Keep content modular and reusable.
Reduce ambiguity for readers.
Simplify onboarding for new writers.
Make your documentation friendlier to automation and AI-assisted tools.

DITA taught us to think in types, not just topics. Markdown lets us practice that thinking with less overhead, using tools that integrate smoothly into today’s development workflows.

If you’ve worked in DITA for years, don’t see that experience as “outdated.” It’s the foundation for building smarter, cleaner, and more maintainable docs-as-code content today.

You can also query the same YAML that powers build-time tables in Astro via a live API, with interactive documentation available on Swagger Docs.