Topics, maps and bookmaps

Topics

A topic file holds one topic: topic, concept, task, reference, glossentry or troubleshooting. Its root element needs an id, and every id inside one topic must be unique.

<task id="install-cli">
  <title>Install the CLI from a checkout</title>
  <shortdesc>Build the opend command and check that it runs.</shortdesc>
  <taskbody>
    <steps>
      <step><cmd>Clone the repository.</cmd></step>
    </steps>
  </taskbody>
</task>

The page URL is the file's path without its extension, so topics/start/install-cli.dita is served at /topics/start/install-cli.html. Keep file names stable: links from outside the site depend on them.

A topic may contain nested topics, which render as sections of the same page and can be linked with file.dita#nested-id. A <dita> wrapper may hold several topics; the first is the page.

Maps

The root map named by map in opend.config.yaml defines the navigation, in document order:

<map>
  <title>OpenD Documentation</title>
  <mapref href="keys.ditamap"/>
  <topicref href="../topics/overview.dita"/>
  <topichead navtitle="Get started">
    <topicref href="../topics/start/install-cli.dita"/>
  </topichead>
  <topichead navtitle="Embedded help" product="embed">
    <topicref href="../topics/help/help-overview.dita"/>
  </topichead>
</map>

• topicref adds a topic. Without a navtitle, the navigation shows the topic's title as the reader sees it, so a conditional phrase in a title stays filtered.
• topichead adds a heading with a navtitle and no page. A heading with nothing visible under it is left out of that reader's navigation.
• topicgroup, frontmatter and backmatter group entries without adding a level.
• mapref (or a topicref to a .ditamap) includes a submap at that point. Its entries and keys are merged in; reference cycles are errors.
• toc="no" publishes a topic without listing it in the navigation.
• keydef and processing-role="resource-only" define keys without adding navigation. See Use keys for names, links and images.

A topic is published to a reader only when a navigation entry they can see points at it and the topic's own root passes their filter. Filtering attributes on a map entry apply to everything under it.

Bookmaps

A bookmap listed under publications becomes a PDF. Its booktitle/mainbooktitle is the publication title, and chapter, part and appendix entries work like topicref. A bookmap resolves keys in its own keyspace, so pull shared keys in with a mapref. See Define a publication with a bookmap.