YAML-based DITA structured authoring
A practical, working implementation of DITA topic types (task, concept, reference) in YAML, with strict schema validation and semantic rendering without XML.
This subsection demonstrates a working, practical structured-authoring system inspired by the OASIS DITA architecture. Authors author standalone documentation topics in clean YAML files, validate their structural integrity against a strict schema, and render them as accessible, semantic documentation pages within the existing manual.
Overview and architecture
Traditional DITA (Darwin Information Typing Architecture) relies on XML source files, complex DTDs or XSD schemas, and the Java-based DITA Open Toolkit (DITA-OT). This tooling overhead often hinders adoption in modern docs-as-code and developer-centric workflows.
Our implementation adopts a pragmatic intermediate approach: capturing the **semantic rigor of DITA** (separating task, concept, and reference; distinguishing imperative commands from supplementary info; supporting nested substeps, non-sequential choices, and step results) through **human-readable YAML files** that version-control cleanly with standard Git diffs.
Working example topics
Explore the three working topic examples rendered directly from project YAML source files:
Replace a lawnmower blade
Remove a worn or damaged rotary blade and install a replacement safely following standard mechanical precautions.
Information typing in technical documentation
Understand the foundational principles of topic-based structured authoring and why tasks, concepts, and references are separated.
Illustrative reference data: Lawnmower blade specifications and maintenance parameters
Illustrative lookup specifications, sample fastener torque limits, blade tolerances, and maintenance wear criteria for rotary lawnmowers.
Choosing the right information type
The core principle of information typing requires that each topic addresses a distinct reader intent and remains independently understandable:
Procedural instructions
To accomplish a specific objective with verifiable outcomes.
- Answers: How do I?
- Structure: Prerequisites, context, sequential steps, results.
- Rule: At least one imperative command (`cmd`) is required.
Explanatory information
To build accurate mental models of architecture, rules, and relationships.
- Answers: What is it? Why does it work this way?
- Structure: Intro, sections, subsections, examples.
- Rule: Do not force procedural instructions into concepts.
Factual and lookup information
For rapid lookup of specifications, options, dimensions, or syntax.
- Answers: What are the parameters / values?
- Structure: Structured tables, property dictionaries, code blocks.
- Rule: Optimized for quick scanning and lookup.
YAML schema to semantic HTML mapping
The table below details how declarative YAML constructs map directly into standard semantic HTML elements without unnecessary decorative markup or client-side scripts:
| DITA / YAML construct | Rendered HTML element | Semantic role and behavior |
|---|---|---|
prereq | <section class="dita-prereq"> <ul> | Prerequisites list before initiating procedure |
context | <section class="dita-context"> <p> | Background rationale and situational context |
steps | <ol class="dita-steps"> | Ordered sequential list maintaining step progression |
step | <li class="dita-step"> | Single procedural step container |
cmd | <div class="dita-cmd"> | Actionable imperative instruction (visually prominent) |
info | <div class="dita-info"> | Supplementary guidance distinguished from the command |
substeps | <ol class="dita-substeps" type="a"> | Subordinate ordered list maintaining nested order |
choices | <ul class="dita-choices"> | Unordered choice list distinct from sequential steps |
stepresult | <div class="dita-stepresult"> | Expected verification outcome of an individual step |
result | <section class="dita-result"> | Overall procedural completion state |
postreq | <section class="dita-postreq"> | Follow-up actions, cleanup, or next operations |
tables | <table> <thead> <tbody> | Accessible data table with scoped column and row headers |
notes | <aside role="note"> | Accessible semantic callout with appropriate role |
related | <nav class="dita-related-links"> | Semantic links grouped by target relationship type |
Authoring workflow and adding topics
To add a new structured topic to the documentation base:
- 1. Create the YAML file
Create a file in `src/content/dita/en/<id>.yaml` (and its localized counterpart in `src/content/dita/fr/<id>.yaml`). The `id` property must match the file basename.
- 2. Declare the type and structure
Specify `type: task`, `type: concept`, or `type: reference`. Populate mandatory `title` and `shortdesc` fields.
- 3. Validate locally
Run `npm run validate:dita` or `npm test`. The validator checks syntax, schema conformance, and referential integrity.
- 4. Preview in Astro
Start `npm run dev` and navigate to `http://localhost:4321/<lang>/structured-authoring/dita-yaml/<id>/` to verify layout.
Deliberate scope and excluded constructs
This system is deliberately designed as a focused structured-authoring model, not a complete XML DITA processor:
- No fine-grained inline XML tags: Tags such as `uicontrol`, `wintitle`, `filepath`, `userinput`, `systemoutput`, or `varname` are intentionally omitted. Ordinary text and Markdown inline syntax (`code`, **bold**) are used instead.
- No XML serialization or DITA-OT pipeline: No heavyweight Java/XSL-FO processing is needed; Astro renders pure static HTML directly.
- No DITA maps or conref processing: Site hierarchy is maintained through standard navigation, and modular reuse leverages Astro component patterns.
Automated local validation
To ensure structural integrity before publishing, authors can run automated local checks:
# Run dedicated DITA YAML corpus validation:
npm run validate:dita
# Run full repository test suite (including DITA checks):
npm test
# Validate site-wide information architecture links:
npm run validate:ia