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.
-
Pick a key for each screen. Keys are words separated by dots, from general to specific.
For example
tenantsandtenants.detail. Dots matter: a key falls back to its parents, sotenants.detailopens thetenantstopic until a more specific one exists. Keys use letters, digits,_and-between the dots. -
Add a
resourceidto the topic'sprolog, 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.
appnameis the app name your widget passes;appidis the key. -
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> -
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. -
Optional: put a
resourceidinside a nested topic to open the page at that section.
Results
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.