Hi Jeff,
The basic rules are:
- The DITA navigation hierarchy is used for the WebHelp structure.
- DITA topic references contribute to navigation hierarchy.
- DITA map references do not contribute to navigation hierarchy, unless they are contained in a <topichead> element (whose purpose is to contribute navigation hierarchy at the map level).
For example, consider the following:
webhelp_1.png
Note that the books A and B use a bare
<mapref>, while books C and D use a
<mapref> in a
<topichead>. The WebHelp presentation is as follows:
webhelp_2.png
Notice that for books C and D, the tile text comes from the navigation title and
not the book title! Essentially, map references are "transparent" containers for their content.
When you click on a tile, the content presented comes from whatever navigation structure exists under that tile's level.
You can also use
<topichead> to group multiple items together:
Code: Select all
<topichead>
<topicmeta>
<navtitle>Collection With Books C and D</navtitle>
</topicmeta>
<topichead>
<topicmeta>
<navtitle>Book C</navtitle>
</topicmeta>
<mapref href="bookC.ditamap"/>
</topichead>
<topichead>
<topicmeta>
<navtitle>Book D</navtitle>
</topicmeta>
<mapref href="bookD.ditamap"/>
</topichead>
</topichead>
There is some related discussion here that helps explain things:
https://dita-users.groups.io/g/main/top ... 6138#46795
including a reference to a DITA-OT plugin I use that enhances map references to contribute their own navigation hierarchy, avoiding the need to manually add
<topichead> structure and hardcode title text.
Here is my WebHelp testcase, if you want to experiment with it:
webhelp_structure.zip