Lower authoring friction
Writers and engineers work in Markdown and Git instead of a specialized XML editor and CCMS, far more contributors can help.
Documentation migration - DITA to Markdown migration
Move from a DITA/CCMS toolchain to a lean Markdown Docs-as-Code workflow, with a deliberate plan for topic structure, reuse, and conditional output. We convert topics and maps, resolve reuse, and rebuild your navigation for a modern static site.
Why teams move from DITA to Markdown
Modern tooling
DITA-OT already publishes HTML and Markdown. Migration makes sense when your team needs a different authoring, review, or platform model; we compare that benefit with the structured-content capabilities you would give up.
Keep what works
We preserve the parts of your DITA reuse and structure that earn their keep, and drop the overhead that doesn’t.
How we run the migration
01
Analyze maps & topics
We inventory your ditamaps, topic types (concept/task/reference), keys, and conref usage to understand how your content is actually assembled.
02
Convert with structure intact
Topics convert to Markdown/MDX; ditamap hierarchy becomes site navigation. We keep semantic structure (task steps, notes, tables) rather than flattening it.
03
Resolve reuse
Conrefs and key references are resolved or re-implemented as snippets/includes in the target system, so shared content stays shared instead of being copy-pasted everywhere.
04
Validate & redirect
We check converted topics against the agreed acceptance criteria, map the source URLs, and validate redirects and destination links before launch.
What breaks in a DITA → Markdown migration
The bulk conversion is the easy part. These are the failure modes we’re actually paid to handle.
Conref and key references silently flattening into duplicated content
Specialized/constrained DITA that generic converters mishandle
Conditional profiling (audience/platform filters) with no Markdown equivalent
Complex tables (CALS) that degrade in a naive conversion
Loss of topic typing and semantic structure that downstream tooling relies on
Broken output URLs from the old DITA-OT publishing pipeline
Start with a $990 Migration Pilot
We migrate a representative slice of your DITA docs to Markdown, with the sample size and conversion scope confirmed before work starts. You receive a live preview and a proposal for the full move; the pilot fee is credited if you proceed.
Commonly asked questions
Not necessarily. Conrefs and keys are resolved or re-implemented as snippet includes in the target platform (using native features, plugins, or custom components as needed). We assess which reuse is load-bearing and preserve it, and inline the rest.
Yes. DITA conditional profiling (audience, product, platform) has no direct Markdown equivalent, so we map it to the target’s mechanism, build-time variants, tabs, or separate outputs, based on how your content is actually used.
It depends on your team. Sphinx suits engineering-heavy docs with strong reuse and reference needs; Docusaurus and MkDocs suit lighter, faster-moving docs. We’ll recommend a target as part of the pilot rather than guessing up front.
We agree acceptance criteria, run structural and link checks, and compare representative topics and reuse patterns with the source. Unsupported constructs are flagged for review. The proposal defines any exhaustive topic-by-topic review; it is not implied by a bulk conversion.
From our blog
How we scope large docs migrations
Why migrations fail in scope-setting, not execution, and how a representative pilot slice turns assumptions into an accurate estimate.
Reference documentation that never drifts
Define once, generate everything else. Machine-readable schemas and code annotations keep reference docs in sync with the source automatically.
Take back control of your documentation
Your docs are a business asset, own them like one. Docs-as-code in Git ends vendor lock-in and export limits.
Moving from DITA to Markdown?
Share your source platform and migration requirements. We review the content, URLs, and integrations before proposing the move.