Using DITA Conditional Text in Markdown Files

One of the advantages of DITA is the ease in which you can apply conditional text. Because, in most instances, I use markdown when working with DITA Open Toolkit (DITA-OT), I wanted to see how well conditional text works in markdown files. In DITA-OT, you can apply conditional text to markdown files. I will show some examples in this post.

Create Markdown Files

First, we'll populate three markdown files:

first.md

# First Section
 
This document shows the use of conditional text in markdown files.

second.md

# Second Section
 
This is the second section.

conditions.md

# Conditions
 
This is a test.
 
This paragraph is visible to <span audience="novice">novice</span><span audience="expert">expert</span> users.
 
This paragraph is only for novice users. {audience="novice"}
 
This paragraph is only for advanced users. {audience="expert"}
 
 
## Table {audience="expert"}
| Header 1 | Header 2 | Header 3 |
| -------- | -------- | -------- |
| Row 1    | Data A   | Data B   |
| Row 2    | Data C   | Data D   |

NOTE: We apply several conditions in the conditions.md file.  

1. <span audience="novice"></span> and <span audience="novice"></span>. These tags are used to apply conditions at the word-level.
2. {audience="novice"} and {audience="expert"}. These tags are used at the paragraph-level and section level.

Create ditamap File

Next, we'll create a ditamap file to set the structure of the files that we populated above.

my_map.ditamap

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
    <title>User Guide</title>
 
    <topicref href="first.md" format="markdown">
        <topicref href="conditions.md" format="markdown"/>
    </topicref>

    <topicref href="second.md" format="markdown" audience="novice" />
</map>

 NOTE: We apply audience="novice" condition to second.md.

Create Ditaval File

Finally, we with create a ditaval file to indicate which conditions to include and exclude.

my_rules.ditaval

<?xml version="1.0" encoding="UTF-8"?>
<val>
    <prop action="include" att="audience" val="expert"/>
    <prop action="exclude" att="audience" val="novice"/>
</val>

Run DITA-OT with Filter (First Pass)

We will run DITA-OT with the ditaval settings shown above. These settings show the audience=expert.

 ~/dita-ot-x.x/bin/dita --input=my_map.ditamap --format=PDF--filter=my_rules.ditaval

Results

NOTE: That the Second Section is not shown and only entries with audience=expert are shown.

Run DITA-OT with Filter (Second Pass)

We will use the following ditaval settings:

my_rules.ditaval (Second Pass)

<?xml version="1.0" encoding="UTF-8"?>
<val>
    <prop action="exclude" att="audience" val="expert"/>
    <prop action="include" att="audience" val="novice"/>
</val>

These settings show the audience=novice.

We will run DITA-OT again with the new ditaval settings.

 ~/dita-ot-x.x/bin/dita --input=my_map.ditamap --format=PDF--filter=my_rules.ditaval

Results

NOTE: That the Second Section is shown, the Table section is not shown, and only entries with audience=novice are shown.