41 lines
2.8 KiB
Markdown
41 lines
2.8 KiB
Markdown
# Generated evidence registries in Docusaurus
|
|
|
|
Use this pattern when a canonical Markdown corpus must also expose a cross-client registry such as systems, products, suppliers, or services.
|
|
|
|
## Preserve the canonical layer
|
|
|
|
- Keep client/source Markdown and its validator authoritative.
|
|
- Generate ignored MDX copies and registry pages at build time.
|
|
- Never edit generated pages to improve evidence; improve canonical table rows and regenerate.
|
|
- Emit a machine-readable registry JSON alongside human-readable pages.
|
|
|
|
## Conservative identity model
|
|
|
|
1. Parse only the canonical, schema-defined table under the expected heading.
|
|
2. Preserve every source observation with client ID, client route, relationship, meaning/context, contractor, evidence, and confidence.
|
|
3. Normalize case, whitespace, dashes, and Markdown decoration for matching only; preserve observed labels for display.
|
|
4. Maintain explicit reviewed alias rules in durable source data. Merge only unmistakable product/shared-service identities.
|
|
5. Keep composite labels separate unless evidence proves their components and relationships.
|
|
6. Scope generic labels such as “official website”, “institution portal”, or “virtual exhibition” to the client; identical wording across clients does not prove one shared system.
|
|
7. Use stable hash-derived registry IDs/slugs so later insertions do not renumber established records.
|
|
|
|
## Docusaurus integration
|
|
|
|
- Use a separate `@docusaurus/plugin-content-docs` instance with its own `id`, generated path, route base, and sidebar file.
|
|
- Include every docs-plugin route base in local-search configuration.
|
|
- A flat sidebar can be produced by generating all docs into one directory and using `{type: 'autogenerated', dirName: '.'}`; range directories create folder categories.
|
|
- Keep existing client slugs explicit when changing generated-directory layout.
|
|
- Validate source rows, unique records, generated routes, observation totals, representative pages, JSON output, and search-index terms after the real production build.
|
|
|
|
## Deployment verification behind authentication
|
|
|
|
A successful Actions run is not sufficient. First prove `HEAD == origin/main` and that the run's `head_sha` matches. Then verify deployment.
|
|
|
|
For an authentication-protected Pages ingress:
|
|
|
|
- unauthenticated public `302` to the configured OAuth start path is expected, not a publish failure;
|
|
- do not weaken or bypass authentication for users;
|
|
- verify content through an authorized browser session or the internal static-site service/backend when operational access permits it;
|
|
- check the homepage, one canonical dossier, registry index, one generated registry dossier, machine-readable JSON, and search index;
|
|
- distinguish ingress/authentication changes from static publication failures before rolling back application code.
|