Skip to main content

In-app help links

The Better Comply application opens this documentation site from contextual Help controls on its pages. This page is the contract between the two: it explains how a page maps to a documentation slug and the rules that keep those links from breaking.

Who this is for

Operators and the web application maintainers. Readers who just want to use the product can skip this page.

The map​

The canonical mapping from an application surface (route or page component) to its documentation slug lives in a machine-readable file at the root of this documentation project, deeplinks.json. Each entry is:

{ "surface": "QualityReviewQueuePage", "route": "/quality/review-queue", "slug": "/admin/quality-audit/review-queue" }

The full help URL is docsBaseUrl + slug, where docsBaseUrl is set per environment by the application.

The application does not hard-code documentation URLs in components. It reads one environment variable, VITE_DOCS_URL, and resolves links through a single helper (docHref(slug) / docSlugForPath(pathname)). The in-app Help Center shows an Open the full documentation link that resolves the current route to its slug and opens the matching page in a new tab.

// VITE_DOCS_URL=https://docs.better-comply.example.com
const DOCS_BASE_URL = import.meta.env.VITE_DOCS_URL;

export function docHref(slug: string): string {
  return `${DOCS_BASE_URL}${slug}`;
}

The link is gated on VITE_DOCS_URL: when it is not configured for an environment, the in-app affordance is simply not shown (never a broken link).

Stability rules​

Slugs are frozen once published

A slug listed in deeplinks.json is a published contract. Do not rename or move a documentation page without keeping the old slug working, or live applications will link to a 404.

  • To move a page, add a client-side redirect from the old slug to the new one (see @docusaurus/plugin-client-redirects) and only then update deeplinks.json.
  • The documentation build runs with onBrokenLinks: 'throw', so an internal link to a removed slug fails the build. Run npm run build before merging any change that touches slugs.
  • When you add a new in-app Help link, add the matching entry to deeplinks.json in the same change.