dita-topic
dita-topic
is a custom converter for Asciidoctor that converts a single AsciiDoc file to a corresponding DITA 1.3 topic.
In combination with asciidoctor-dita-vale and dita-convert, this project can be used to rapidly convert AsciiDoc content to DITA:
-
Identify incompatible markup in the AsciiDoc source file:
$ vale source_file.adoc
-
Convert the AsciiDoc file to a generic DITA topic:
$ asciidoctor -r dita-topic -b dita-topic source_file.adoc
-
Convert the generic DITA topic to a specialized DITA concept, reference, or task:
$ dita-convert -gt task source_file.dita
Installation
Install the asciidoctor-dita-topic
Ruby gem:
$ gem install asciidoctor-dita-topic
Usage
To use the custom converter on the command line, load it with the -r dita-topic
option and then select dita-topic
as the backend output format with -b dita-topic
:
$ asciidoctor -r dita-topic -b dita-topic your_file.adoc
This creates a new file, your_file.dita
, in the same directory as your_file.adoc
. You can also convert multiple files at the same time:
$ asciidoctor -r dita-topic -b dita-topic *.adoc
Important
|
$ dita -i converted_file.dita -f xhtml To produce slightly more readable errors, you can also use $ xmlstarlet val -e -s path_to_dita-ot_directory/plugins/org.oasis-open.dita.v1_3/schema-url/technicalContent/xsd/topic.xsd converted_file.dita |
Supplying attribute definitions
If your AsciiDoc files use attributes that are defined outside of these files, you can supply the attribute definitions on the command line with the -a attribute=value
option:
$ asciidoctor -r dita-topic -b dita-topic -a attribute=value your_file.adoc
You can provide multiple -a attribute=value
options at the same time. Providing relevant attribute definitions is especially important if your document contains conditional content.
ifeval
conditionsYour AsciiDoc files include a number of ifeval
statements that provide different content for different versions of the product you are documenting:
ifeval::["{ProductNumber}" == "1"]
...
endif::[]
ifeval::["{ProductNumber}" == "2"]
...
endif::[]
To ensure that the converted DITA files include all content for version 2 of your product, run:
$ asciidoctor -r dita-topic -b dita-topic -a ProductNumber=2 *.adoc
Enabling author lines
AsciiDoc topics are expected to be included in other files and therefore should not contain author line definitions. In most cases, lines that directly follow the topic title are intended as first paragraphs. For this reason, author lines are disabled by default. To avoid losing content during conversion, as a workaround, the dita-topic
converter interprets the raw content of the author line as a paragraph and issues a warning.
To enable processing of author lines as metadata, set the value of the dita-topic-authors
to on
:
$ asciidoctor -r dita-topic -b dita-topic -a dita-topic-authors=on your_file.adoc
Disabling floating titles
Unlike AsciiDoc, DITA does not support floating titles and only allows titles to be assigned to a limited number of elements. To avoid losing content during conversion, as a workaround, the dita-topic
converter uses the following markup by default:
<p outputclass="title"><b>Floating title</b></p>
To disable this behavior, set the value of the dita-topic-titles
to off
:
$ asciidoctor -r dita-topic -b dita-topic -a dita-topic-titles=off your_file.adoc
Disabling callouts
Unlike AsciiDoc, DITA does not support callouts as a method to add annotations to specific lines in verbatim blocks. To avoid losing content during conversion, as a workaround, the dita-topic
converter uses XML entities for circled numbers.
To disable this behavior, set the value of the dita-topic-callouts
to off
:
$ asciidoctor -r dita-topic -b dita-topic -a dita-topic-callouts=off your_file.adoc
Disabling include directives
By default, Asciidoctor resolves all include
directives before converting the file. To only convert the contents of the selected file, specify the -S secure
option:
$ asciidoctor -r dita-topic -b dita-topic -S secure your_file.adoc
Adding short descriptions
DITA provides the <shortdesc>
element which allows the user to describe the purpose of the topic and is often used as preview text in search results. To replicate this behavior, the dita-topic
converter recognizes a paragraph preceded by the [role="_abstract"]
attribute list and adds the outputclass="abstract"
attribute to it. The dita-convert Python package transforms such a paragraph to <shortdesc>
during conversion to a specialized DITA concept, reference, or task.
For example, to designate a paragraph as a short description, use the following AsciiDoc markup:
[id="topic-id"]
= Procedure title
[role="_abstract"]
A short description of the procedure module and what it helps the
user accomplish.
An introductory paragraph.
Adding semantic markup
Unlike AsciiDoc, DITA provides a number of semantic elements for software components such as file names, commands, or command-line options. To replicate this behavior, the dita-topic
converter recognizes the following roles assigned to monospace (`
) inline text:
AsciiDoc Role |
DITA Element |
command |
|
directory |
|
filename |
|
option |
|
variable |
|
For example, to describe a file name, use the following AsciiDoc markup:
Read the [filename]`/etc/passwd` file to see the complete list of
available user accounts.
Warnings
Despite aspiring to avoid losing content during conversion and produce a valid DITA output, there are limitations to what is possible because of the differences between the two markup languages. When the dita-topic
converter encounters a possible problem, it prints a warning to standard error output in the following format:
asciidoctor: WARNING: dita-topic: The warning message
This possible warning messages are as follows:
Admonition titles not supported in DITA |
AsciiDoc allows you to add a custom title to any admonition by including |
Author lines not enabled for topics |
AsciiDoc interprets the first line that directly follows the document title as an author line. Because topics are not expected to have author lines, |
Block titles not supported in DITA |
AsciiDoc allows you to include |
Callouts not supported in DITA |
AsciiDoc allows you to use |
Examples not supported within object in DITA |
AsciiDoc allows you to use an example block anywhere in the document. Unlike AsciiDoc, DITA only allows examples to appear directly in the topic body. |
Floating titles not supported in DITA |
AsciiDoc allows you to use floating titles anywhere in the document. Unlike AsciiDoc, DITA does not support floating titles. |
Inline breaks not supported in DITA |
AsciiDoc provides multiple ways to insert line breaks in paragraphs, such as inserting |
Nesting of sections not supported in DITA |
AsciiDoc allows you to nest sections up to 5 levels deep. Unlike AsciiDoc, DITA does not allow the |
Page breaks not supported in DITA |
AsciiDoc allows you to use |
Possible invalid reference: reference |
AsciiDoc allows you to cross reference by using an ID no matter if this ID is defined within or outside of the converted document. Unlike AsciiDoc, DITA requires both the target ID and the ID of the target topic to be included in the cross reference if the reference leads outside of the current file. As |
Sidebars not supported in DITA |
AsciiDoc allows you to assign any block the |
STEM support not implemented |
AsciiDoc provides multiple ways to insert Science, Technology, Engineering and Math (STEM) expressions in the document, including the |
Table footers not supported in DITA |
AsciiDoc allows you to set the |
Thematic breaks not supported in DITA |
Asciidoc allows you to use |
Copyright
Copyright © 2024, 2025 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.