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.

The other help layer: the in-app quick-help panel​

This documentation site is one of two help surfaces, and they are connected. Inside the application, the Help Center panel (opened by the ? button in the top bar, or the ? keyboard shortcut) offers three tabs:

  • Quick Start — a short, role-based checklist for getting going.
  • FAQ — searchable answers to common questions.
  • This Page — short contextual tips for the screen you are on, together with an Open the full documentation link that jumps to this site's page for that screen (the deep link described above).

The inline "Learn more in the Help Center" links dotted through the app open that This Page tab, so a reader who wants the long-form explanation is one step from the matching page here. The short tips live with the application; the in-depth guidance lives on this site. When a screen's workflow changes, both are updated together so they never disagree.