dita-map

dita-map is a command line utility that converts a single AsciiDoc file to a DITA map. It recognizes the document title as the map title and uses the include directives and their respective leveloffset values to compose the tree of <mapref> and <topicref> elements.

Install the asciidoctor-dita-map Ruby gem:

gem install asciidoctor-dita-map

To convert a single AsciiDoc file to a DITA map, supply it as an argument to the dita-map command:

$ dita-map your_file.adoc

By default, dita-map creates a new file, your_file.ditamap, in the same directory as the source file. You can supply multiple files at the same time or use wildcards:

$ dita-map *.adoc

When you do not supply any file names or specify - as the first argument, dita-map reads from standard input and prints the result to standard output. For example:

$ echo 'include::task.adoc[leveloffset=+1]' | dita-map
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
  <topicref href="task.dita" navtitle="A topic title" type="task" />
</map>

To change the output file name or location, use the -o or --out-file command-line option:

$ dita-map input_file.adoc -o output_file.ditamap

To print the result to standard output, use - as the output file name. For example:

$ dita-map input_file.adoc -o -
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
  <title>A map title</title>
  <mapref href="another_map.ditamap" format="ditamap" type="map" />
  <topicref href="concept.dita" navtitle="A concept title" type="concept">
    <topicref href="task.dita" navtitle="A task title" type="task" />
  </topicref>
</map>

If your AsciiDoc files use custom attributes that are defined externally, you can supply the attribute definitions with the -a or --attribute command-line option:

$ dita-map -a attribute_name=attribute_value your_file.adoc

You can supply multiple -a/--attribute options at the same time.

If listing individual attribute definitions is impractical, you can supply AsciiDoc files that contain the attribute definitions with the -p or --prepend-file command-line option:

$ dita-map -p definition_file.adoc your_file.adoc

The supplied file is prepended to each AsciiDoc file during conversion. You can supply multiple -p/--prepend-file options at the same time or combine them with the -a/--attribute options to construct your attribute definitions. If you define the same attribute twice this way, the value defined by the -a/--attribute option takes precedence.

To correctly recognize when to use the <topicref> and <mapref> elements and what values to assign to their type attributes, dita-map recognizes the following :_mod-docs-content-type: attribute definition values in included AsciiDoc files:

For example, to ensure an included AsciiDoc file is recognized as a DITA map, add the following line at the top of the file:

:_mod-docs-content-type: MAP

Copyright © 2026 Jaromir Hradilek

This program is free software, released under the terms of the MIT license. It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.