TypesDitac

TypesDitac is a TypeScript port of the XMLmind DITA Converter (ditac) preprocessor that generates a unified file from a DITA map and all its topics.

Supported Input

• DITA 1.0, 1.1, 1.2 and 1.3 maps and topics. The DTDs and schemas are bundled, so no network access is needed.
• Lightweight DITA:
  • XDITA (XML)
  • HDITA: .html, .htm, .shtml, .xhtml, .xhtm, .xht
  • MDITA: .md, .markdown, .mdown, .mkdn, .mdwn, .mkd, .rmd
• DITAVAL conditional processing.
• Keys and key scopes, conref and conref push, map references, relationship tables, metadata cascading, and index terms.

In addition to CommonMark, MDITA files may use these Markdown extensions:

• tables
• definition lists
• footnotes
• abbreviations
• inserted text (++text++)
• strikethrough
• subscript (~text~) and superscript (^text^)
• admonitions (note, tip, warning, caution, danger, etc.)
• attribute blocks
• keyrefs

Installation

TypesDitac requires Node.js 24 or newer.

Option 1: Install globally with npm

npm install -g typesditac

Then run:

typesditac <map.ditamap> [options]

Option 2: Clone and build from source

git clone https://github.com/maxprograms-com/TypesDitac.git
cd TypesDitac
npm install
npm run build

Then run:

node ./dist/typesditac.js <map.ditamap> [options]

Usage

Run typesditac or node dist/typesditac.js and the program prints this help text:

Usage:
  typesditac <map.ditamap> [options]

Required:
  <map.ditamap>             DITA map to process

Options:

  --output-dir <dir>        Where to write the output files
                            (default: <map-dir>/out/ditac/)
  --chunking <none|single|auto>
                            How to split the output into multiple files
                            (default: none); "auto" follows chunk hints in
                            the map itself
  --merge                   Write everything combined into a single,
                            self-contained XML file instead of the chunk
                            and list files
  -o, --output <file>       Where to write that combined file; only used
                            with --merge
                            (default: <output-dir>/<map-name>.xml)
  -v, --ditaval <file>      DITAVAL file (conditional filtering profile) to
                            apply
  -c, --catalog <file>      XML catalog to use while resolving referenced
                            files
  -l, --lang <lang>         Language for messages printed by this program
                            (default: system locale)
  --doc-lang <lang>         Default content language, used when the map
                            itself does not specify one
  --extract-images          Extract embedded SVG/MathML/LaTeX formulas as
                            separate image files instead of leaving them
                            inline
  --resources <dir>         Folder where referenced images and other non-XML
                            files are copied, relative to the output folder
                            (default: img)
  --media <screen|print>    Target medium, affects which content is
                            included/excluded (default: print)
  --toc                     Add a generated table of contents at the front
                            of the document
  --index                   Add a generated index at the back of the
                            document
  --frontmatter <spec>      Add other generated sections at the front; see
                            SECTION SPEC below
  --backmatter <spec>       Add other generated sections at the back; see
                            SECTION SPEC below
  -p, -param <name> <value> Specifies a conversion parameter: extended-toc
                            or title-page; see PARAMETERS below
  -h, --help                Show this help message

PARAMETERS (for -p|-param <name> <value>):
  extended-toc              Which entries are listed in the table of
                            contents generated by --toc or a "toc" section
                            of --frontmatter/--backmatter, besides the body
                            entries (chapters, sections, etc.). Only used
                            with --merge. Values:
                              none         no other entries (default; any
                                           unrecognized value acts as
                                           none)
                              frontmatter  also the entries contained in
                                           <frontmatter>, listed before
                                           the body entries in a
                                           ditac:frontmatterTOC element
                              backmatter   also the entries contained in
                                           <backmatter>, such as the
                                           glossary and the index, listed
                                           after the body entries in a
                                           ditac:backmatterTOC element
                              both         frontmatter and backmatter
                                           entries
                            Entries of individual glossary items are never
                            listed.
  title-page                Controls the ditac:titlePage entry (title,
                            author, etc.). Values:
                              auto | none  the entry is generated only
                                           when the map has a title
                                           (default); rendering choices
                                           between them are left to the
                                           stylesheets, so they make no
                                           difference to this tool
                              other        URI of a custom title page:
                                           the entry is generated even if
                                           the map has no title
  Any other parameter name is rejected.

SECTION SPEC (for --frontmatter/--backmatter):
  spec -> page [ ',' page ]*        one or more pages, separated by commas
  page -> section [ '+' section ]*  sections sharing one page, separated
                                    by '+'
  section -> toc|figurelist|tablelist|examplelist|equationlist|indexlist

--toc and --index are shortcuts for --frontmatter toc and --backmatter indexlist. When both a shortcut and the corresponding spec are given, the shortcut wins.

Output

Unified XML document

With --merge, TypesDitac writes a single XML document to <output-dir>/<map-name>.xml, or to the file given with -o. Its root element is the DITA <map>. It contains all the topics, fully preprocessed: keys and conrefs resolved, filtering applied and metadata cascaded.

It also contains placeholder elements marking where generated sections go: <ditac:titlePage>, <ditac:toc>, <ditac:figureList>, <ditac:tableList>, <ditac:exampleList>, <ditac:equationList> and <ditac:indexList>. Which of them appear depends on --toc, --index, --frontmatter, --backmatter and -p title-page.

Intermediate files

Without --merge, TypesDitac keeps the intermediate files it uses to build the unified document. They are written to the output folder, which is <map-dir>/out/ditac/ unless --output-dir is given:

• <map-name>.ditac: one or more chunk files with a <ditac:chunk> root element, containing the preprocessed topics and the placeholder elements.
• ditac_lists.ditac_lists: information about the whole document, with a <ditac:lists> root element: the chunks and the topics each one contains, topic numbers and titles, and the entries of the table of contents, the lists of figures, tables, examples and equations, and the index.

--chunking controls how many .ditac files are written:

• none (default): a single chunk file. chunk attributes in the map are ignored.
• single: a single chunk file. Only the select-* part of chunk attributes is kept.
• auto: one chunk file per chunk requested by the map's chunk attributes. This only applies with --media screen; with --media print (the default), auto behaves like none.

Resources

Images and other non-XML files referenced by the topics are copied to img/ in the output folder. Use --resources to change the folder name.

With --extract-images, embedded SVG, MathML and LaTeX formulas are saved as separate files, copied to the same img/ folder, and replaced in the output by <image> elements that reference them.

Examples

Write a unified XML document with a table of contents and an index:

typesditac manual.ditamap --merge --toc --index -o build/manual.xml

Apply a DITAVAL profile for on-screen output:

typesditac manual.ditamap --merge --ditaval web.ditaval --media screen

Add a table of contents on its own page, followed by the lists of figures and tables sharing a second page:

typesditac manual.ditamap --merge --frontmatter "toc,figurelist+tablelist"

Keep the intermediate files, split as requested by the map's chunk attributes:

typesditac manual.ditamap --output-dir build --chunking auto --media screen

Messages and Diagnostics

Warnings and errors are printed to stderr. When processing fails, the program exits with code 1.

Use -l to choose the language of these messages. Available languages are Czech (cs), Dutch (nl), English (en), French (fr), German (de), Italian (it), Japanese (ja), Norwegian Bokmål (nb), Norwegian Nynorsk (nn), Polish (pl), Russian (ru), Simplified Chinese (zh) and Spanish (es). The default is the system locale.

-l does not change the document. To set the language of the content when the map does not specify one, use --doc-lang.

XML Catalogs

TypesDitac bundles an XML catalog with the DTDs and schemas for DITA 1.0 to 1.3, Lightweight DITA, MathML 2 and 3, and SVG. It is installed at dist/catalog/catalog.xml inside the package.

-c replaces the bundled catalog instead of adding to it. If your catalog only adds entries, for example for a DITA specialization, end it with a nextCatalog pointing back to the bundled one:

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <!-- your entries -->
  <nextCatalog catalog="/path/to/node_modules/typesditac/dist/catalog/catalog.xml"/>
</catalog>

Using TypesDitac as a Library

The package also exports the preprocessor and its components. process() returns the unified document as a TypesXML XMLDocument, ready to be processed in memory or saved:

import { Catalog, XMLDocument, XMLWriter } from "typesxml";
import {
    DiagnosticLog, Filter, I18n, LoadDocument, LoadedDocuments, TypesDitacPreprocessor
} from "typesditac";

const i18n: I18n = I18n.load(DiagnosticLog.I18N_DIRECTORY, "typesditac", "en");
const diagnostics: DiagnosticLog = new DiagnosticLog(i18n);
const loader: LoadDocument = new LoadDocument(diagnostics, new Catalog(LoadDocument.DEFAULT_CATALOG));
const documents: LoadedDocuments = new LoadedDocuments(loader, diagnostics);
const preprocessor: TypesDitacPreprocessor = new TypesDitacPreprocessor(documents, diagnostics);

preprocessor.setFrontMatter([["toc"]]);
preprocessor.setBackMatter([["indexlist"]]);

const filter: Filter = Filter.load("web.ditaval", loader, i18n);
const unified: XMLDocument = preprocessor.process("/docs/manual.ditamap", "/docs/out/manual.xml", filter);
XMLWriter.writeDocument(unified, "/docs/out/manual.xml");

diagnostics.print((message: string): void => console.error(message));

TypesDitacPreprocessor also has setChunking(), setMedia(), setLang(), setExtractAsImage(), setResourceHandler(), setExtendedToc() and setForceTitlePage(), matching the CLI options. writeChunkOutput(), getChunkDocuments() and getListsDocument() give access to the intermediate files.

To load other input formats, implement DocumentLoaderFactory and register it with DocumentLoaderFactories.register(). The factory is chosen by file extension.

---

Credits

TypesDitac is a port of the preprocessor of XMLmind DITA Converter, written by Hussein Shafie, Copyright © 2017–2025 XMLmind Software. The TypeScript port is Copyright © 2026 Maxprograms SAS.

Legal

This project is licensed under the MPL 2.0 License. See the LICENSE.md file for details.