documentation-docusaurus/references/behavioral-acceptance-for-doc-portals.md

Behavioral acceptance for Docusaurus documentation portals

Use this gate when a request includes interactive behavior such as theme switching, section navigation, or local search. A successful build and Actions run prove compilation/publication only; they do not prove the requested behavior works.

Requirement-to-proof matrix

Write the matrix before implementation and require one direct proof per request:

Requirement	Source/config proof	Built-artifact proof	Browser proof
Light/dark mode	disableSwitch: false; separate light/dark tokens	both selectors present in compiled CSS	click toggle; verify data-theme, persisted theme, and computed colors all change
Dedicated section sidebars	separate docs-plugin instances, sidebar files, and docSidebar navbar items	each section route renders its own sidebar labels	open every top-menu section and inspect Docs sidebar; ensure unrelated section labels are absent
Local search	local-search dependency/theme configured; no hosted provider	generated search index contains representative terms from every docs instance	type a query, wait for loading to end, confirm a visible result, and open it

Do not report completion until every requested row has a browser proof or an explicitly stated blocker.

Multi-section sidebars

A differently named category inside one shared sidebar is not a dedicated sidebar. For top-level menu areas that must own navigation:

1. Keep one default docs instance for overview/global theme compatibility.
2. Add one @docusaurus/plugin-content-docs instance per section with a unique id, content path, routeBasePath, and sidebarPath.
3. Give each sidebar an independently named root, such as projectsSidebar.
4. Configure each navbar entry as type: 'docSidebar', with both docsPluginId and sidebarId.
5. Give each section index slug: / relative to its plugin route.
6. Build and inspect every top-level route, not only the source configuration.

Static local-search verification

Use @easyops-cn/docusaurus-search-local as a theme and include every docs route base in docsRouteBasePath. Search must remain static/browser-local, with no Algolia or hosted crawler credentials.

Prefer hashed: 'filename' on static hosting that redirects requests carrying query strings. With hashed: true, the theme fetches search-index.json?_=HASH; a host that redirects query-string asset requests can leave the search field indefinitely loading even though search-index.json exists. Filename hashing emits and fetches search-index-HASH.json directly.

Verification:

1. Assert exactly one search-index*.json exists in build/.
2. Inspect it for representative terms from overview and every docs plugin.
3. Serve the production build under the real configured baseUrl.
4. Type a representative query in the navbar.
5. Confirm loading ends and a visible result appears.
6. Open the result and verify its route.
7. After deployment, fetch the exact generated hashed index from the Pages backend and repeat term checks.

Theme debugging

If the toggle exists but the appearance does not change, inspect hard-coded colors before changing Docusaurus configuration. Typical root causes are:

• html, body fixed to the dark background;
• navbar/sidebar/footer colors fixed with !important;
• custom homepage CSS modules defining only dark values;
• light and dark Prism themes configured identically.

Move component colors behind semantic variables. Define a complete light palette in :root, [data-theme='light'] and dark overrides in [data-theme='dark']. For CSS modules, use :global([data-theme='light']) .page to override page-level tokens. Browser verification must compare computed colors, not only the data-theme attribute.

Reporting discipline

Do not substitute these for behavioral acceptance:

• local TypeScript success;
• production-build success;
• successful CI;
• a deployed HTML marker;
• presence of the toggle/search input/sidebar container.

Those are supporting checks. Report the pipeline only after matching it to the intended commit SHA, and report the feature only after exercising it.