documentation-docusaurus/references/multi-section-evidence-portals.md

Multi-section evidence portals in Docusaurus

Use this pattern when top-level areas such as Overview, Clients, Systems, Methodology, and Data are distinct user tasks and a shared sidebar makes navigation noisy.

Dedicated docs instances

Give each top-level area its own @docusaurus/plugin-content-docs instance, content path, route base, and sidebar file. One instance must remain the default plugin (omit id) because themes such as local search may call the default docs hooks while rendering global pages, search, or 404 routes. Assign explicit IDs only to the additional instances.

For each sidebar, use an independently named autogenerated root:

const sidebars = {
  sectionSidebar: [{type: 'autogenerated', dirName: '.'}],
};

When moving generated indexes into their section directories:

• give each index slug: / within its plugin;
• update navbar, footer, homepage, and cross-document links;
• include every route base in local-search configuration;
• remove obsolete shared docs only after the new routes exist;
• validate each top-level route by a distinctive content marker after production build.

Large registry sidebar hierarchy

A dedicated sidebar is not sufficient if hundreds of dossiers remain at its root. For large entity sections, use exactly two first-level entries:

1. Overview — the section's registry/index document.
2. Registry — an expandable category containing every individual dossier in stable domain order.

const sidebars = {
  entitiesSidebar: [
    {type: 'doc', id: 'entity-directory', label: 'Overview'},
    {
      type: 'category',
      label: 'Registry',
      collapsed: false,
      collapsible: true,
      items: registryItems,
    },
  ],
};

For generated content, build registryItems deterministically from canonical IDs or generated filenames. Be careful when deriving Docusaurus document IDs from filenames with numeric prefixes:

• a filename such as 001-client-name.md commonly resolves to document ID client-name, because Docusaurus treats 001- as a position prefix;
• if removing the generated position prefix leaves a basename beginning with a digit, Docusaurus may retain the complete filename ID—for example, 0002-112-mobile-application.md may resolve to 0002-112-mobile-application, not 112-mobile-application;
• the safest new-generator design is an explicit stable id in frontmatter;
• for existing generators, derive IDs with the observed rule and verify both an ordinary dossier and the first numeric-leading dossier in the production build.

After building, inspect rendered section indexes—not only configuration source—and assert that Overview, Registry, and the first several ordered dossier labels are present. Also retain exact route-count validation for all dossiers.

Reusable evidence cards

Wide relationship/evidence tables become difficult to scan. Generate MDX pages that import a reusable React card component and pass structured props for entity, relationship, context, contractor, confidence, and source links. Keep the component generic and keep evidence extraction in the generator.

Requirements:

• preserve claim-level direct links;
• render confidence and role explicitly;
• retain a link to the canonical entity dossier;
• use responsive semantic markup (article, header, dl, lists);
• preserve the site's shape language, including square edges when required;
• validate that all generated records contain cards and that the old table signature is absent.

Generated identifier provenance

If registry identifiers are hash-derived, label them as internal generated IDs everywhere users encounter them: registry introduction, record page, methodology, and provenance/data documentation. State the exact derivation (for example, the first ten hexadecimal characters of a SHA-1 digest of the canonical identity key), its determinism boundary, and that it is not a public-source identifier.

Per-record reference indexes

A record should preserve precise claim-level citations and also expose a de-duplicated ## References index for scanning and reuse.

• Client pages: extract all direct Markdown URLs from the canonical dossier while generating the MDX copy; preserve first-seen label/order and de-duplicate by URL.
• Derived system pages: combine direct URLs from every source observation with canonical system-analysis evidence URLs; de-duplicate by URL.
• Do not replace claim-level links with the index.
• If there is no URL, say so explicitly rather than inventing one.
• Validate exact coverage counts: every generated entity dossier and every generated derived-record dossier must have a References heading.

Verification sequence

1. Run source generation and schema validation.
2. Run TypeScript checks.
3. Run the real production build and route validator.
4. Assert exact dossier/reference/card counts and absence of obsolete table signatures.
5. Serve the build locally and request every top-level index plus representative entity and derived-record routes, checking distinctive markers.
6. Commit/push, prove local/remote SHA equality, inspect the Actions run matching that SHA, and verify deployed content when the protected backend is reachable.
7. Treat expected public authentication redirects separately from content publication.