92 lines
5.2 KiB
Markdown
92 lines
5.2 KiB
Markdown
# 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:
|
|
|
|
```ts
|
|
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.
|
|
|
|
```ts
|
|
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.
|