To collapse a sprawling map-and-topic repository into a single self-contained file, our DITA topics to composite conversion takes each root map and produces one composite DITA document per publication — keys resolved, submaps expanded in true reading order, cross-references rewritten so they still work inside the file. It is the DITA transformation that gives reviewers, translators, archivists and downstream systems the one clean file they actually want, without flattening the repository your authors work in.
A split repository is superb for authoring and expensive to move. Send a single topic to a subject-matter expert and they open a file that conrefs three others and keyrefs a warning defined in a map they do not have; they see placeholders, not content. Hand a translation vendor a topic tree and they must reconstruct the key space before they can even read the real text. Archive a release and you archive a dependency graph that only resolves if every file and every map is present and correct. The reuse machinery that makes authoring efficient becomes friction the moment content leaves the CCMS.
Producing a resolved composite per publication removes that friction. The reviewer reads real prose; the translator receives self-contained input; the archive is a single artifact that will still render years from now. And you never had to flatten your source — you flattened a delivery copy and kept everything.
We start where your publications start. A root map — any map that nothing else references — is treated as one publication, and each one produces a single composite DITA file. Nested submaps are expanded in the order a reader would meet them, and the hierarchy they came from is recorded rather than dissolved, so collapsing a map is not an act of amnesia. The record rides in markers that never affect DITA validity — your DTD will not even see them — and it can instead be made visible to a downstream tool, or stripped entirely, when that suits the destination better. Keys are resolved in that publication's own key space, which is exactly the detail cheaper approaches get wrong: the same key can legitimately mean two different things under two different maps, and resolving it in the wrong context silently produces the wrong sentence in the wrong book. Topic-to-topic links become references that still work inside the single file. And the images and assets that publication actually uses travel with it, rather than the whole media library.
How far the resolution goes is your decision, not ours — and the default is better than a trade-off: key text and link targets are filled in while the references themselves are kept, so the very same composite reads complete to a reviewer and still round-trips into a CCMS that resolves keys its own way. Reuse can also be inlined all the way down to literal text for a translator who must never meet a placeholder, or deliberately left untouched for a destination that insists on resolving everything itself. The collapsed hierarchy can be represented the way your rendering expects it. And what counts as a publication is tuned to how your organisation actually defines one, rather than to a convention we picked for you.
Your repository is read to find the maps that nothing else references — your real publications — and everything each one depends on is inventoried from there: submaps, topics, reused blocks, key definitions, images and assets.
Each root map becomes one composite. Submaps are expanded in reading order, topics are placed in sequence, and cross-references between them are rewritten so they resolve inside the single document instead of pointing at files that are no longer separate.
Keys are resolved in that publication's key space and reused content is pulled in as agreed, so the composite carries real, readable content rather than references waiting for a system that can resolve them.
Every delivered composite is re-parsed and checked by the conversion's own validation engine: well-formedness, duplicate topic ids, broken in-document references and content references, and copied assets that are not where their links say they are. A per-publication report plus a run summary — maps expanded, topics merged, keys applied, assets copied, every issue found — is delivered with the build, so you see what happened rather than trusting that it did.
You receive one composite DITA file per publication with the assets it uses, a reading order faithful to the original, and a record of the map hierarchy it came from — ready for review, translation, archival or a downstream target. Re-runs are deterministic — the same repository yields a byte-identical composite — so an archived deliverable can be regenerated and verified years later.
A generic run identifies your publications and produces resolved composites with sensible defaults. Customer-specific tailoring aligns the output with how your organisation defines a publication and with whatever happens to the file next: which maps count as publications, whether reuse is resolved to literal text or preserved for a system that re-resolves it, how the collapsed hierarchy should be marked for your rendering, and what happens when two chapters reference the same topic — embedded once, embedded twice, or flagged for a decision.
| Downstream need | How we configure the merge |
|---|---|
| Translation vendor must never see a key or a placeholder | Every key and reused block is resolved to literal text, one composite per deliverable unit — so what the translator reads and quotes is exactly what your reader will read. |
| Re-import into a CCMS that owns its own key space | Key references are preserved so the destination resolves them its own way, and publication boundaries are set to match how that CCMS divides content. |
| Long-term archive that must render standalone | A fully resolved composite with its own assets — one durable artifact that still opens when the toolchain around it has moved on. |
| Will expanding a map lose a topic? | Content conservation is enforced: a collapse never drops a topic, a table cell or a line of text — and every composite is re-parsed and verified, ids, references and assets included, before delivery. |
Teams improvise this today, usually with a publishing-toolkit preprocess or a hand-rolled script that inlines topics — and then meet the hard parts: keys that resolve differently depending on which map is the context, cross-references that break the moment files merge, and a naive inline that dissolves the map structure entirely. DocentraX treats it as a first-class DITA transformation: resolution you control, key contexts that stay correct per publication, and hierarchy that survives the collapse, all verified by a validation pass that re-parses every delivered composite and reports, publication by publication, exactly what it found. It is the exact inverse of our composite DITA to topics service, and it feeds cleanly into downstream work such as DITA to DocBook when a single-file source is the easier thing to hand to another vocabulary.
Your authoring stays granular and reuse-friendly where that pays off — in the repository — while everyone downstream gets content in the shape they actually need: a single, self-contained, resolved document per publication. Review cycles shorten because reviewers read finished prose instead of placeholders, translation gets cleaner and cheaper because there is nothing left for the vendor to reconstruct, and archives become durable single artifacts. The repository and the deliverable stop being in tension, because you can generate the deliverable on demand and lose nothing on the way.
Point the conversion at your repository. It finds each root map, follows everything that map depends on, and writes one self-contained composite DITA file per publication — submaps expanded in true reading order, keys resolved, and cross-topic links rewritten so they still work inside the single file.
A root map is a map that no other map references — the top of a publication's hierarchy. The DITA topics to composite conversion treats each root map it finds as one publication and produces a single composite for it, and where your organisation draws publication boundaries differently, that definition is tuned to match yours.
By default you get both at once: keys are resolved in each publication's own key space — text and link targets filled in — while the references themselves are kept, so the composite carries real content and still round-trips into a system that re-resolves. Full inlining to literal text, or leaving references entirely untouched, are each a setting away.
Yes — and with the default you rarely have to choose, because resolved text and preserved references coexist in the same file. For a destination that must do all resolution itself, references can be kept untouched, with publication boundaries set to match how that CCMS divides content; the same repository can also produce a fully inlined output for translation in a separate run.
No. Content conservation is enforced across every DocentraX conversion — expanding a map never drops a topic or a line of text — and every composite is re-parsed and verified before delivery: well-formed, free of duplicate topic ids and broken in-document references, with every copied asset accounted for in the report that accompanies the build.
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