Skip to content
Menu
OpenD Documentation
Version 0.1
Sign in

Context-sensitive help in your apps

Show OpenD help inside your own web app, in a side panel that opens on the help for the current screen and is filtered for the signed-in user.

The help is served live from the docs repository, through the same reader filter as the docs site. A user on release 0.1 with the embed product sees exactly the help their organization is entitled to, no more.

How the pieces fit

  1. Authors tag topics with context keys using DITA's resourceid: <resourceid appname="opend-console" appid="tenants.detail"/>. See Tag topics with context keys.
  2. Authors map routes to keys in help-contexts.yaml, so an app can just send its current path. See help-contexts.yaml reference.
  3. The app loads the widget, tells it the current route, and opens the panel from a help button. See Embed the help widget.
  4. The app's backend signs a short-lived token for its signed-in user, which the panel exchanges for a session. See Sign embed tokens in your backend.
  5. OpenD resolves the context for that reader: the key, then its parents, then the app's default, never a topic the reader cannot see. See How a context resolves, and its fallback rules.

Apps that render help in their own UI can call the JSON API instead of showing the panel: see Help JSON API reference. If your docs site is public and the app needs only what any visitor sees, it calls the API anonymously: no token, no secret, no embedding to turn on.

What the panel shows

  • The topic, compact, with links that stay in the panel.
  • "In this section": the topic's visible children and siblings in the navigation.
  • Search over the topics this reader can see, and nothing else.
  • "Open in full docs", which opens the page on the docs site in a new tab.

The project theme applies in the panel too.

Turning it on

Embedding is off until you set OPEND_EMBED_SECRET and OPEND_EMBED_ORIGINS on your OpenD server. Until then nothing under /embed exists, and /api/v1/help answers only anonymous requests on a public site.

Ask the operator of your docs site to turn on embedding for your app's origins and to share the embed secret with your backend team. A public site's anonymous JSON API needs neither.

To check context help before publishing, use the previewer's help lab.