help-contexts.yaml reference

Maps each app's routes to context keys, so an app can open help by sending its current path, and sets the key to use when nothing more specific matches.

Format

The file lives at the docs root. Part of this site's own file:

apps:
  opend-console:
    default: overview
    routes:
      /: overview
      /tenants: tenants
      /tenants/:tenant: tenants.detail
      /tenants/:tenant/**: tenants.detail
      /billing/**: billing
      /editor/**: editor
      /editor/:repo/conflicts: editor.conflicts

Field	Meaning
`apps.<name>`	One entry per app, named as in `resourceid appname` and in the widget's `app` option. Letters, digits, `_` and `-`.
`default`	Optional. The key used when the requested key, and every parent of it, has nothing this reader can see.
`routes`	Route pattern to key, in any order. Optional.

Route patterns

Segment	Matches	Example
`tenants`	that word, ignoring case	`/tenants`
`:name`	any one segment	`/tenants/:tenant`
`*`	any one segment	`/files/*`
`**`	zero or more segments; last segment only	`/billing/**`

Every pattern starts with /.
Query strings, fragments, empty segments and trailing slashes in the path are ignored, and percent-encoded segments are decoded, so /Tenants/acme/?tab=users matches /tenants/:tenant.
A segment containing *, :, ? or # other than as above is invalid, and so is ** before the last segment. Both are invalid-help-contexts errors.

Which route wins

When several patterns match a path, the most specific wins:

the one with more literal segments;
then one without **;
then the longer pattern;
then the one earlier in the file.

So for /editor/docs/conflicts, /editor/:repo/conflicts (two literals) beats /editor/** (one literal). For /tenants/acme, /tenants/:tenant beats /tenants/:tenant/**, which has the same literals but a **.

Checks

Every route and default must name a key that some topic declares with resourceid, or a key with such a parent: tenants.detail is fine while only tenants exists. Anything else is an unknown-context error. A path that matches no route opens the default.