Skip to content

Tag topics with context keys

Declare which screen of which app a topic helps with, using DITA's standard resourceid element, in the topic or on its map entry.

  1. Pick a key for each screen. Keys are words separated by dots, from general to specific.

    For example tenants and tenants.detail. Dots matter: a key falls back to its parents, so tenants.detail opens the tenants topic until a more specific one exists. Keys use letters, digits, _ and - between the dots.

  2. Add a resourceid to the topic's prolog, naming the app and the key.
    <prolog>
      <resourceid appname="opend-console" appid="tenants"/>
      <resourceid appname="opend-console" appid="billing"/>
    </prolog>

    A topic can answer several keys, and several apps. appname is the app name your widget passes; appid is the key.

  3. Or put it on the map entry, in its topicmeta. Map entries are checked before topics.
    <topicref href="../topics/hosting/admin-api.dita">
      <topicmeta><resourceid appname="opend-console" appid="builds"/></topicmeta>
    </topicref>
  4. Optional: point one key at different topics for different readers.
    <topicref href="../topics/notes/release-1.dita" release="1">
      <topicmeta><resourceid appname="console" appid="whats-new"/></topicmeta>
    </topicref>
    <topicref href="../topics/notes/release-2.dita" release="2">
      <topicmeta><resourceid appname="console" appid="whats-new"/></topicmeta>
    </topicref>

    Conditions on the resourceid, on the elements around it and on the map entry all apply. Each reader gets the first target whose conditions pass and whose topic they can see. Two unconditional targets for one key are an error, duplicate-context, because the second could never be shown.

  5. Optional: put a resourceid inside a nested topic to open the page at that section.

A resourceid without both appname and appid is an error, invalid-resourceid. Keys on topics the build-time filter removes are dropped. For example, this site tags its admin API reference sections with the opend-console keys repos, builds, orgs, readers and audit.