Home
DITA map files
Topic hierarchy
In DITA, the sequence and hierarchy of the topics to be published are defined in the ditamap through nested topicref elements.
Controlling the top node (default topic)
DITA publishing tools sometimes process the hierarchy of a ditamap slightly differently for different target output formats. A workaround can be used to achieve greater consistency between different outputs to avoid confusing readers.

Introduction
Information types and topics
Topics are the building blocks of modular documents, and organising topics by semantic information types is one of the architectural features of DITA.
DITA map files
- Purpose of ditamap files
  DITA map files are used for defining the topics of a publication, specifying the topic sequence, and controlling linking between topics.
- Topic manifest
  Any topics referenced anywhere in the ditamap will be processed into the output publication.
- Topic hierarchy
  In DITA, the sequence and hierarchy of the topics to be published are defined in the ditamap through nested topicref elements.
  - Designing a topic hierarchy
    A well-designed topic hierarchy will make the reader's task of finding information in a publication easier.
  - Heading levels and ditamaps
    The topic hierarchy in the ditamap is used to generate heading levels and styles in page layout outputs.
  - Controlling the top node (default topic)
    DITA publishing tools sometimes process the hierarchy of a ditamap slightly differently for different target output formats. A workaround can be used to achieve greater consistency between different outputs to avoid confusing readers.
  - Excluding topics from the output TOC
    When generating an output which includes a TOC, you may want to generate a topic from your ditamap but not have it appear in the output TOC. This is achieved through the toc and linking attributes of the topicref.
  - Creating a Glossary of Terms
    A Glossary of Terms is defined in a ditamap using either standard topicref elements to glossary entry topics, or using glossref elements (introduced in DITA 1.2).
- Relationship tables
  Relationship tables are used to store linking relationships between topics in a collection in the ditamap, rather than in individual topics. Linking relationships are defined in a table-like structure, with rows in the table determining which topics are linked to which.
- Linking relationships
  DITA encourages the linking relationships to be stored outside the topic content. Links can be generated from topic hierarchies, relationship tables, and related-links section links.
- Inheritance and cascades in ditamaps
  Properties in ditamaps sometimes cascade from parent elements to child elements. Some values in ditamaps also override the equivalent values in referenced topics.
- Embedded (or nested) ditamaps
  The technique of using embedded, or nested, ditamaps can make it easier to manage documents by separating complex collections of topics into a number of smaller, simpler collections.
- DITA map vocabulary
- The bookmap feature
  Bookmaps are a specialisation of the base DITA map information type. Like ditamaps, bookmaps are containers for structure and context metadata, and do not contain any content. Bookmaps are used to describe page layout publishing outputs such as books, articles, manuals and research papers. They contain information structures that are specific to linear publications, such as tables of figures, title pages, chapters, sections and parts.
Syntax and mark-up
Language and punctuation
Graphics and figures
Cross-referencing
Cross-references are a means of binding individual topics into a coherent and navigable document.
Content re-use
Metadata, conditional processing, and indexing
The DITA documentation process
DITA authoring concepts
Moving from style-based authoring to a structured authoring methodology such as DITA requires a radically different approach to writing.

Controlling the top node (default topic)

DITA publishing tools sometimes process the hierarchy of a ditamap slightly differently for different target output formats. A workaround can be used to achieve greater consistency between different outputs to avoid confusing readers.

When a ditamap file is processed into a Help format, the first topic in the ditamap hierarchy becomes the first (or default) topic displayed. In some Help outputs, it also becomes the topic displayed when the Home button in the tri-pane navigation panel is selected.

Some Help formats allow for the nomination of a topic other than the first topic as the default page, and perhaps yet another topic as the Home topic. DITA currently has no facility to record such an alternative Home topic in the ditamap.

In Eclipse Help outputs, the TOC generated from the ditamap includes the map element as its top node. This can cause some confusion to the user, because the title highlighted in the TOC is different from the title of the displayed topic.

In the first example following, an Eclipse Help system is displaying an information set using the collection's home address. The TOC is highlighting the ditamap's map element title, while the topic associated with the first topicref in the ditamap is displayed. The second example shows the same document, open at the home address, in Microsoft HTML Help format. In this type of output, the map element in the ditamap is ignored when the TOC is generated.

Screen capture showing unlinked node at top of TOC in Eclipse Help output — Figure 1. Example of map title (with no associated topic) displaying in Eclipse Help TOC

Screen capture showing normal linked node at top of TOC in HTML Help output — Figure 2. Example of first topic title displaying in HTML Help TOC

One workaround is to structure the ditamap so that the first node is a childless topicref element with its toc attribute set to no, and ensuring that the title of the map element is the same as that first topic. This will result in the first topic not appearing in the TOC, creating the illusion that the top node links to the topic. The mark-up for the map would therefore follow this pattern:

<map title="Introduction to World Time Pro">
  <topicref href="c_WorldTimePro.dita" toc="no"/>
  <topicref href="c_CalculatingTime.dita">
    <topicref .... />
    <topicref .... />
    ....
  </topicref>
  <topicref href="c_FractionConverter.dita" />
  ....
</map>

Although this workaround will deliver a good result, take care that focussing on the output format (the form) doesn't result in compromises to the information design (the content), so that the separation of content and form is honoured.