Skip to main content
Version: v2

Internal vs. Merchant Content Guide

This guide defines which content is internal-only and must be hidden in the Merchant build (DOCS_AUDIENCE=merchant).

How the Merchant Build Works​

The Merchant build is triggered by setting the environment variable:

DOCS_AUDIENCE=merchant yarn build

Content is excluded from the Merchant build in two ways:

MechanismWhat It Excludes
exclude in docusaurus.config.jsEntire folders/files — never built at all
<Audience include="internal"> componentInline sections within a page — stripped at build time

Excluded Folders (Entire sections not built for Merchant)​

The following top-level folders are excluded entirely from the Merchant build:

FolderReason
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 like EIMP events

These are configured in the exclude array inside docusaurus.config.js under presets → classic → docs.

Inline Internal Sections (<Audience include="internal">)​

Use the <Audience> component to hide specific sections within a page that merchants should not see. The section is stripped from the Merchant build but remains visible in the internal build.

Syntax​

<Audience include="internal">

This content is only visible in the internal docs build.

</Audience>

What to Wrap as Internal​

The following types of content must be wrapped in <Audience include="internal">:

Content TypeExamples
Infrastructure / architecture detailsAKS cluster config, multi-cloud gateway topology, Splunk setup
Internal processing flowsSequence diagrams, wallet merge logic, enterprise settings logic
Internal API endpoints or admin APIs13--Admin.md, internal-only routes
Sensitive error root causesDB errors, upstream dependencies, internal retry logic
Staff-facing notesImplementation notes, known issues not yet customer-visible
Webhook internal mappingInternal event → external event translation tables
HCP-internal URLsHCP API catalog internal links, internal JIRA/Confluence references

What Does NOT Need to Be Wrapped​

Merchant-facing content should not be wrapped — leave it 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
  • Customization and theming docs
  • Sandbox/staging credentials guidance

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

Checklist Before Publishing a New Page​

When adding a new doc that will appear in both builds, run through this checklist:

  • 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 the content is stripped correctly