Skip to content
Menu
OpenD Documentation
Version 0.1
Sign in

Release notes for 0.1

The first release of OpenD: the build and filter core, the hosted path, embedded help and PDF publications.

Build, filter and preview

  • A DITA 1.3 subset parsed in TypeScript, with line and column for every problem: topics, maps, bookmaps, keys, conref and conkeyref.
  • One applicability rule: product and feature against entitlements, release ranges against the reader's version, other attributes through a build-time DITAVAL. Fail-closed, with conditional keys resolved per reader.
  • opend validate with text, JSON and GitHub annotation output; opend build; and opend preview with "Preview as", a staff view that marks conditions, live reload and git refs.
  • A starter template with sample content, a bookmap, reusable chunks, a theme and a validation workflow.

Hosted path

  • Push to publish: a GitHub webhook queues a build, the worker builds and validates the exact commit, and a failing push never goes live.
  • Release lines: 1.x and 2.x docs live side by side, each reader served their own line.
  • OIDC reader sign-in, matched by verified email; filtered pages, navigation and images, cached per entitlement set.
  • Site-wide search: a search box in the header of every page and a results page that finds only what the reader can see in their release, with stemming, phrases and prefix matching. See Search the docs.
  • An admin API with an audit log, a seed command, one Docker image for every role, a Compose file, S3-compatible blob storage, published images, and a Railway runbook.
  • An admin console for staff readers at /admin: site access, the docs repository and builds, people, sign-in, the GitHub connection and the editor, from the browser. See Run your site from the admin console.
  • Connect GitHub: the console creates and installs a GitHub App for the site, its credentials stored encrypted. See Connect GitHub from the admin console.

Web editor

  • A browser editor on its own host, for authors who do not use Git. Developers sign in with GitHub; other authors with company OIDC, once an administrator adds them with opend-server editor add-user.
  • DITA source editing with a live preview of unsaved text, validation problems listed next to the source, new topics from templates, and preview as an org.
  • Saves are commits to the author's own branch, crediting them. Publishing opens one pull request, shows what the branch rules still require, and merges when nothing blocks it.
  • The main branch is merged in on every page open and save. Authors resolve conflicts by keeping their version, the current one, or editing by hand; structural conflicts go to a developer.

See Edit docs in the browser.

Context-sensitive help

  • resourceid context keys with parent fallback, and route patterns in help-contexts.yaml.
  • An embeddable help panel with per-reader search, the OpenDHelp widget and <opend-help-button>, host-signed tokens and partitioned sessions.
  • A JSON API for apps that render help themselves, and the previewer's help lab.

PDF publications

  • Bookmaps printed per reader through the same filter, with a cover, linked contents, an outline and the project theme.
  • Print HTML and PDFs in the previewer; cached per release and entitlement set on the server.

Known limitations

  • Not supported yet: DTD specialisation, conrefend, relationship tables, key scopes and branch filtering. See Supported DITA subset.
  • The contents list in PDFs has no page numbers.
  • One docs site and one embed secret per deployment.
  • The web editor edits DITA source; there is no visual editor yet. It edits one repository per deployment.
  • No operator console yet.