Version: v2

Internal vs. Merchant Content Guide

This guide covers everything a contributor needs to know about the two-audience build system: what content belongs in each build, how builds are produced, how they are deployed, and how to author content correctly.

Internal content must never be exposed to merchants

The docs-internal image contains engineering guides, architecture diagrams, admin API references, internal error details, and other sensitive operational content. This image must only be deployed to the Test environment (developers.healthsafepay.com). Deploying it to any merchant-accessible URL is a security violation. If you are unsure whether content is safe for merchants, treat it as internal and wrap it accordingly.

1. The Two Builds

Every pull request targeting develop (opened, updated, or synchronized) produces two distinct container images in parallel:

Build	Workflow	ACR image	`DOCS_AUDIENCE`	Audience
Merchant	`.github/workflows/build-merchant.yml`	`docs-merchant`	`merchant`	External merchants and partners
Internal	`.github/workflows/build-internal.yml`	`docs-internal`	`internal` (default)	Internal team only

DOCS_AUDIENCE is set at yarn build time. Content is permanently baked into each image — there is no runtime flag. The two images are content-distinct.

What each build contains

Content area	Merchant	Internal
Integration guides, API request/response schemas	✅	✅
Error codes visible to merchants	✅	✅
`<Audience include="internal">` inline sections	❌ stripped	✅
`docs/05-engineering-guide/`	❌ excluded	✅
`docs/contributing-guide/`	❌ excluded	✅
`docs/06-high-level-designs/`	❌ excluded	✅
Internal wallet management operations (`5-customers/`)	❌ excluded	✅
Third-party integrations (`8-third-party-integrations/`)	❌ excluded	✅
Internal API spec (`/engineering-guide/internal-api-v2/`)	❌ excluded	✅
OpenAPI `[Learn More](...)` internal links	❌ stripped	✅
AI Assistant (ChatBot, AI SearchBox)	❌ hidden	✅

2. How Deployments Work

The Helm values file for each GitHub Environment overrides image.repository, binding the environment permanently to one image. The deploy workflows only set the image tag — the repository is fixed by the values file and cannot be overridden by the caller.

GitHub Environment	Helm values file	Image deployed	URL
`Dev`	`deployment/config/helm/values-dev.yaml`	`docs-merchant`	docs.healthsafepay.com
`Test`	`deployment/config/helm/values-test.yaml`	`docs-internal`	developers.healthsafepay.com

Environment isolation is automatic. The operator only selects Dev or Test — the correct image follows. It is structurally impossible to deploy docs-internal through the Dev environment or vice-versa via the standard workflows.

Deployment approval issues

After each build, the shared CI workflow creates a GitHub issue labelled deployment-requested. Comment /deploy on the issue to trigger deployment.

The issue from build-merchant targets Dev automatically.
The issue from build-internal is automatically patched by a post-build job (fix-deployment-issue) to target Test — no manual action needed.

Deploying manually

If you need to deploy without using an approval issue, use the deploy-manually workflow:

Select environment Dev (merchant) or Test (internal).
Enter the image tag (7-char commit SHA).
Run — the correct image is pulled automatically via the values file.

3. How Content Exclusion Works

Content is excluded from the Merchant build by two mechanisms:

Mechanism	Scope	Configured in
Audience exclude globs	Entire folders — never compiled	`config/audience-exclude-globs.js` (single source of truth)
`<Audience include="internal">` component	Inline sections within a page	Applied by authors in MDX source

Single source of truth for folder exclusions

Folder-level exclude globs live in one file: config/audience-exclude-globs.js.

Both consumers import from it, so the site build and the search index stay in sync:

docusaurus.config.js → presets → classic → docs.exclude
scripts/docs/generateSearchPages.js → search index generation

To add or remove an excluded folder, edit only config/audience-exclude-globs.js. Do not hardcode globs in the two consumer files.

Excluded folders (entire sections)

Folder	Reason
`docs/05-engineering-guide/`	Internal engineering standards, runbooks, handbook
`docs/contributing-guide/`	Authoring and documentation guidelines
`docs/06-high-level-designs/`	Architecture diagrams and internal design docs
`docs/03-developers/5-convenient-checkout-api/5-customers/`	Internal wallet management operations
`docs/03-developers/5-convenient-checkout-api/8-third-party-integrations/`	3rd-party integration internals (EIMP events)

Inline internal sections

Use the <Audience> component to hide specific sections within a page that merchants should not see:

<Audience include="internal">

This content is only visible in the internal docs build.

</Audience>

The <Audience> tag MUST be capitalized

MDX v3 treats lowercase <audience> as a plain HTML element — the browser ignores it and renders the children unconditionally. Only a capitalized <Audience> is processed as a React component.

✅ <Audience include="internal"> — correct
❌ <audience include="internal"> — content always visible to everyone

No import needed — The component is globally registered via src/theme/MDXComponents.js.

4. What to Mark as Internal

Must be wrapped in `<Audience include="internal">`

Content type	Examples
Infrastructure / architecture details	AKS cluster config, multi-cloud gateway topology, Splunk setup
Internal processing flows	Sequence diagrams, wallet merge logic, enterprise settings logic
Internal API endpoints or admin APIs	`13--Admin.md`, internal-only routes
Sensitive error root causes	DB errors, upstream dependencies, internal retry logic
Staff-facing notes	Implementation notes, known issues not yet customer-visible
Webhook internal mapping	Internal event → external event translation tables
HCP-internal URLs	HCP API catalog internal links, internal JIRA/Confluence references

Does NOT need to be wrapped

Leave visible in both builds:

API request/response schemas
Integration guides and code examples
Error codes and resolutions visible to merchants
Supported payment methods and capabilities
Customisation and theming docs
Sandbox/staging credential guidance

5. AI Assistant

The AI Assistant (ChatBot + SearchBox) is automatically hidden in the Merchant build. No manual wrapping is needed. This includes:

The floating ChatBot sidebar (<ChatBot /> in Root.js)
The AI-powered SearchBox in the Navbar
The "AI Assistant is available!" announcement bar

6. Checklist Before Publishing a New Page

When adding a doc that will appear in both builds:

Does the page contain infrastructure or architecture internals? → Wrap in <Audience include="internal">
Does it have internal-only processing flows or sequence diagrams? → Wrap in <Audience include="internal">
Is it an entire internal-only section? → Add the folder to the exclude list in docusaurus.config.js
Is the page permission metadata set correctly? (permission: [merchant, internal, business])
Run yarn build:merchant locally to verify content is stripped correctly

1. The Two Builds​

What each build contains​

2. How Deployments Work​

Deployment approval issues​

Deploying manually​

3. How Content Exclusion Works​

Excluded folders (entire sections)​

Inline internal sections​

4. What to Mark as Internal​

Must be wrapped in <Audience include="internal">​

Does NOT need to be wrapped​

5. AI Assistant​

6. Checklist Before Publishing a New Page​

Related Documentation​