Native DITA XML ingestion in Astro

This experimental subsection demonstrates how Astro can directly ingest authentic DITA XML topic files covering the three core archetypes of structured authoring (Concept, Task, Reference), validate their semantic structure, and produce clean, accessible HTML while serving the original XML sources byte-for-byte.

The three DITA archetypes

At the core of DITA (Darwin Information Typing Architecture) lies the strict separation of content according to user intent. Each archetype serves a distinct informational purpose:

• Concept (<concept>) : Explains what something is, its background, and why it matters, without prescribing step-by-step procedures.
• Task (<task>) : Describes how to accomplish a specific goal through an ordered sequence of steps (`<step>`), actionable commands (`<cmd>`), and contextual guidance (`<context>`).
• Reference (<reference>) : Provides structured factual data for quick lookups (properties, configuration tables, parameters, syntax rules) without narrative padding.

Demonstration topics

Each topic below is rendered directly from its authentic XML source file:

Concept

Lawnmower

The lawnmower is a machine used to cut grass in the yard.

lawnmower.dita →

Task

Changing the oil in your car

Once every 6000 kilometers or three months, change the oil in your car.

changingtheoil.dita →

Reference

Plug-in configuration file

Theplugin.xmlcontrols all aspects of a plug-in, making each extension visible to the rest of the toolkit. The file uses pre-defined extension points to locate changes, and integrates those changes into the core code.

plugin-configfile.dita →

DITA map and navigation architecture

In the DITA authoring methodology, a topic never hardcodes ‘next page’ or ‘previous page’ links. Topics are independent, self-contained modular units meant for reuse across different publications. It is the DITA map (<map>) that defines the taxonomy, hierarchy, and reading journey for the end reader.

This subsection uses the demonstration map ‘DITA Structured Authoring Demonstration Map’ (collection-type="sequence") to dynamically orchestrate reader progression across all three archetypes:

dita-astro.ditamapView raw .ditamap

1. 1
   Lawnmower Conceptconcept

   Fundamental principles and varieties of lawnmowers.

   lawnmower.dita
2. 2
   Changing the Oiltask

   Routine step-by-step procedure to change engine oil.

   changingtheoil.dita
3. 3
   Plug-in Configuration Referencereference

   Reference specifications for DITA-OT plugin.xml files.

   plugin-configfile.dita

Note on map provenance: While the three XML topic files (lawnmower.dita, changingtheoil.dita, plugin-configfile.dita) are authentic DITA-OT corpus files verified byte-for-byte, dita-astro.ditamap is a local integration fixture authored specifically for this POC. In the upstream dita-ot/dita-ot repository, garage samples (hierarchy.ditamap) and the developer reference (dev_ref.ditamap) reside in separate sample suites without an existing upstream map connecting all three archetypes.

Canonical sources and provenance

All three source files originate from the official DITA-OT repository, preserved byte-for-byte and verified by SHA-256 checksums:

Archetype / resource	Local source	Upstream path	Author / license	Source endpoints
Concept	lawnmower.dita	src/main/samples/concepts/lawnmower.xml	IBM Corp. (2001, 2005) / CPL 1.0 & Apache 2.0	.dita ·.xml
Task	changingtheoil.dita	src/main/samples/tasks/changingtheoil.xml	IBM Corp. (2001, 2005) / CPL 1.0 & Apache 2.0	.dita ·.xml
Reference	plugin-configfile.dita	src/main/doc/dev_ref/plugin-configfile.dita	DITA-OT / Arbortext / Apache 2.0 & CPL 1.0	.dita ·.xml
DITA Map	dita-astro.ditamap	Local integration fixture (see note above)	redaction-technique.org (Demonstration fixture)	.ditamap ·.xml

XML ingestion pipeline and validation tiers

The XML parser implements strict security assertions and a clean three-tier validation policy:

1. Level A — XML well-formedness : The document must follow XML 1.0 syntax. Prior to parsing, entity declarations (<!ENTITY) and remote/local SYSTEM directives are blocked to neutralize XXE and Billion Laughs expansion.
2. Level B — Supported application subset : The root must be <concept>, <task>, or <reference> with a valid id attribute. The title and archetype body (<conbody>, <taskbody> with ordered steps and mandatory commands, or <refbody> with sections and tables) are verified against safe application schemas.
3. Level C — Formal DITA conformance (out of scope) : Formal grammar validation against full OASIS DITA DTDs/XSDs with catalog resolution and specialization checking is deliberately out of scope for this lightweight, self-contained Astro demonstration.

DITA XML to semantic HTML mapping

Archetype	DITA XML element	Semantic HTML output
All	<title> / <shortdesc>	<h1> (titre unique) / <p class="lead"> (description courte unique)
Concept	<conbody> / <p>	<div class="dita-conbody"> / <p>
Task	<taskbody> / <steps> / <cmd>	<div class="dita-taskbody"> / <ol class="dita-steps"> / <li><div class="dita-cmd">
Reference	<refbody> / <section> / <simpletable>	<div class="dita-refbody"> / <section> / <table class="dita-simpletable">

Supported elements and scope limitations

• Supported elements :<map> (avec collection-type="sequence"), <topicref>, <topicmeta>, <concept>, <task>, <reference>, <title>, <shortdesc>, <conbody>, <taskbody>, <context>, <prereq>, <stepsection>, <steps>, <step>, <cmd>, <info>, <substeps>, <stepxmp>, <choices>, <stepresult>, <result>, <example>, <postreq>, <note>, <ul>, <ol>, <dl>, <refbody>, <section>, <simpletable>, <sthead>, <strow>, <stentry>, <codeblock>, <codeph>, <filepath>, <related-links>.
• Unsupported DITA features : Conref/conkeyref transclusion, complex nested sub-maps and deep tree recursion, conditional ditaval profiling, domain specialization, and PDF/XSL-FO compilation.

Comparison with DITA Open Toolkit

This module does not replace DITA-OT for massive enterprise documentation sets requiring multi-channel publishing (PDF, Eclipse Help, RTF) and complex transclusions. Its purpose is to demonstrate that a modern JAMstack site (Astro) can ingest genuine DITA XML topics and deliver an ultra-fast, accessible web experience without Java runtime dependencies.