Modern documentation ships as a Git repository of Markdown that a static-site generator turns into a site. Split DITA to Markdown conversion bridges your structured source and that world: it takes a DITA map or bookmap and its topics and produces a build-ready Markdown documentation tree — one that renders directly on GitHub, builds on GitBook or mdBook with its summary navigation generated, and feeds generators such as Docusaurus and MkDocs. This DITA map to Markdown transformation turns the map hierarchy into a folder tree, generates a navigation file straight from the map, rewrites cross-references as working links, and resolves conref and keyref reuse into real text — so the move to docs-as-code becomes a repeatable build rather than a manual slog you repeat every release.
The tools your developers and modern doc teams prefer — GitHub, GitBook, mdBook, Docusaurus, MkDocs — all speak Markdown-in-Git. If your source is a DITA map with a hierarchy of topics and real reuse, the gap between the two worlds is where documentation projects stall. Hand-converting a map and its topics means recreating the folder structure, writing the navigation by hand and, worst of all, manually resolving every conref and keyref — because a reader on a docs site cannot resolve a DITA key. Miss one and the published page shows a placeholder where a safety warning should be. Do it by hand across a large map and it is an effort that has to be repeated in full, every release, forever.
Converting the whole map in one pass, with reuse resolved and navigation generated, turns that slog into a repeatable build. The DITA source keeps its reuse discipline; the Markdown output is fully resolved and ready to render.
The five-stage lifecycle — Analyse, Transform, Enrich, Validate, Deliver — is applied to a whole publication at once, so the entire map is understood before a single page is written. The output tree contains everything a generator needs:
The map is read to recover the true hierarchy and reading order, and the topic set is inventoried along with its cross-references, conref sources, keyref targets and images — the whole publication is understood as one publication, not as a pile of files. Bookmaps are read as bookmaps: parts, frontmatter and backmatter take their proper places in the reading order, and the book's title and metadata travel into the generated navigation.
The map hierarchy becomes a folder tree, each topic becomes a Markdown page in the dialect your site renders, and cross-references are rewritten as relative Markdown links that genuinely resolve once the site is built. Specialized DITA converts too: an element from a specialization the mapping does not name is rebuilt as its generic base type from its class ancestry — with your DTDs present or without them — so a specialized topic never blocks the build.
Reuse is flattened so nothing lands as a dangling reference: a shared warning pulled into thirty topics by conref appears as real text on all thirty pages, and a keyed product name reads as the product name. Navigation is generated straight from the map — a GitBook/mdBook-style summary or a readme index — notes and cautions render as labelled blockquotes or GitHub-style alerts, with your theme's own admonition syntax available as tailoring, bookmap chapters and appendices can be numbered, and you choose whether the result is a tree of pages or a single concatenated document.
The output is checked so that every internal link resolves, every image reference is intact, no reuse was left unresolved, and — under the content-conservation guarantee — no topic or text was dropped from the map along the way. That guarantee has teeth a pipeline can grip: a topic file that exists but cannot be parsed fails the run with a non-zero exit status, so a CI job gating on the conversion can never silently ship a publication with a topic missing — while a topic genuinely absent from the source keeps its navigation entry, clearly marked and logged rather than papered over.
You receive a documentation tree — folders, pages, navigation and images — matching the layout your generator expects, ready to commit and build into a site.
A generic run gives you a valid Markdown tree with resolved reuse and a standard navigation file, buildable on a typical generator. A customer-specific run targets your exact stack: the navigation convention your generator reads, the dialect it renders, the admonition syntax your theme styles, and the chapter-numbering scheme your docs already use.
| Your concern | How we answer it |
|---|---|
| My generator reads its own navigation format | A GitBook/mdBook-style summary or a readme index is generated straight from the map hierarchy; other generators' navigation formats are wired in as tailoring |
| Reuse must not leak as placeholders | Conref and keyref are flattened into literal text before the page is written, so a reader never meets an unresolved reference |
| My theme has its own admonition syntax | Labelled blockquotes or GitHub-style alerts out of the box; your theme's own syntax as a tailoring option |
| One tree of pages, or one document? | Either — a folder tree of pages, or a single concatenated document, whichever your target consumes |
| Chapters need numbering | Bookmap chapters and appendices are numbered in headings and navigation at the flip of a switch; a bespoke scheme is tailoring |
Concretely: out of the box, the tree renders on GitHub and builds on GitBook or mdBook, summary navigation included. A Docusaurus site expects a sidebar definition and its own admonition syntax; an MkDocs site expects its navigation declared centrally. Those generator-specific conventions are exactly what a customer-specific engagement wires in — same DITA map, your generator's house rules, a tree your team commits rather than rewires by hand before anything will render.
The DITA-to-static-site path is a well-known sore point. The DITA Open Toolkit can emit Markdown, but wiring that output into a specific generator's folder and navigation conventions is fiddly, and naive conversions notoriously leave reuse unresolved — because resolving conref and keyref correctly means understanding the whole map and every key defined across it, not just the topic in front of you. DocentraX resolves reuse into real text as a first-class behaviour, generates the exact navigation the target wants, and preserves the map's reading order, all as a configurable DITA transformation under a content-conservation guarantee. If your source is a single composite DITA document rather than a split map and topic set, use DITA to Markdown instead; and if you first need to split a composite document into the map and topics this conversion consumes, composite DITA to topics produces exactly that.
Your DITA becomes a living documentation site without abandoning the reuse and single-sourcing that made DITA worth adopting in the first place. Authors keep working in a map with conref and keyref; the site is a generated, fully resolved view of that source which rebuilds every release. Docs-as-code teams get the Git-and-Markdown workflow they want, and the organisation gets one source of truth feeding both its structured pipeline and its public site — exactly what multi-channel single-sourcing is meant to deliver.
Point split DITA to Markdown at the DITA map — or bookmap — and its topics. It turns the map hierarchy into a folder tree, writes one Markdown page per topic, generates a navigation file straight from the map, and rewrites cross-references as working relative links. The result is a documentation tree you can commit and build directly, with no hand-wiring in between.
Yes, and this is the heart of it. Conref and keyref reuse is flattened into literal text, so a shared warning or a keyed product name appears as real content on every page that used it. Nothing reaches the site as an unresolved placeholder or a broken include — and your authors keep the reuse intact in the DITA source.
The output is plain Markdown in Git, so it renders directly in GitHub's own in-repo view and builds on GitBook or mdBook, whose summary-file navigation is generated out of the box. Docusaurus, MkDocs and similar generators consume the same tree once their navigation convention is wired in as customer-specific tailoring, and the Markdown dialect and admonition style are chosen per run.
Split DITA to Markdown takes a DITA map plus its topics and produces a folder-tree documentation site with generated navigation and resolved reuse. DITA to Markdown takes a single composite DITA document and produces one Markdown file, or a file-per-topic set. Choose by whether your source is a map-and-topics repository or one composite document.
Yes. A navigation file is generated from the map hierarchy — a GitBook/mdBook-style summary or a readme index — with a bookmap's title and metadata carried into it and chapter and appendix numbering switched on when you want it. You never write the navigation by hand, and it cannot drift out of step with the map.
We'll convert them to DITA free of charge — through the real pipeline, not a demo — and review the output with you. Then we'll discuss pricing one-to-one.
Request your free sample conversion