Skip to main content

Docusaurus Adapter Architecture

The DocusaurusAdapter is responsible for translating the physical filesystem state of a Docusaurus project into Zenzic's universal Virtual Site Map (VSM). Because Docusaurus is a Node.js React framework, Zenzic must emulate its routing logic entirely in Python using static analysis.

The Emulation Contract​

Zenzic does not execute docusaurus build or evaluate JavaScript. Instead, it parses docusaurus.config.ts (or .js) statically to extract the plugin configurations. This allows Zenzic to accurately predict the final URLs generated by the Docusaurus build pipeline.

Route Resolution Semantics​

Docusaurus generates routes based on a combination of filesystem paths and plugin configuration. Zenzic emulates this using the following rules:

  1. Frontmatter Overrides (slug): Docusaurus allows authors to override the default filesystem-based route using the slug frontmatter field. Zenzic respects this:

    • Absolute Slugs: If a slug begins with a / (e.g., slug: /custom), Docusaurus prepends the plugin's routeBasePath. Zenzic correctly prepends the routeBasePath to absolute slugs to prevent false-positive orphaned pages.
    • Relative Slugs: If a slug is relative (e.g., slug: custom), it replaces the last segment of the filesystem path.

  2. Blog Date Extraction: Docusaurus blog posts often use a filename convention like YYYY-MM-DD-slug.md. When generating the URL, Docusaurus extracts the date into path segments (/YYYY/MM/DD/slug/). Zenzic natively parses these filenames using regular expressions to emulate the exact URL generation logic, ensuring that blog posts with dates are mapped correctly into the VSM.

  3. File-Based Linking: Links using absolute paths referencing the source filesystem (e.g., /docs/guide/install.md) are resolved by Zenzic exactly as Docusaurus resolves them, mapping them to their canonical URLs in the VSM.

This architectural approach allows Zenzic to provide zero-false-positive link validation and orphan detection without the overhead of a Node.js runtime or dynamic execution.

Known Limitations & Mitigations​

Zenzic enforces absolute determinism through a pure Python static analysis architecture. Consequently, it does not execute JavaScript or TypeScript. This imposes two strict boundaries when emulating Docusaurus routing semantics:

Webpack @site Aliases​

Zenzic cannot resolve Webpack aliases dynamically. Links utilizing the @site/ alias rely on Node.js module resolution during the Webpack build phase. Because this process is dynamic, static analysis cannot reliably intercept it, and these links will yield Z104 (Missing Internal Route) errors.

Generated Category Indices​

Docusaurus sidebars dynamically generate virtual /category/ routes at runtime via sidebars.js or sidebars.ts. Since Zenzic cannot execute TypeScript to discover these virtual routes, links pointing to generated category indices will yield Z101 (Orphaned File) or Z104 (Missing Internal Route) errors.

Official Mitigation​

To silence these architectural false positives without suffering DQS penalties, you must implement explicit directory policies in your .zenzic.toml (or local .zenzic.local.toml). You should only target the specific directories where these architectural boundaries occur to avoid masking legitimate issues in your main documentation. Do not alter your valid Docusaurus links.

[governance.directory_policies]
# Surgical mitigation for specific files/folders containing generated indices or @site aliases
"website/docs/guides/docs/sidebar/**" = ["Z101", "Z104"]
"website/docs/migration/**" = ["Z104"]

Strategic Note: This limitation is temporary. In v0.12.0, Zenzic will implement the Bridge Architecture. By introducing docusaurus-plugin-zenzic, the Python engine will ingest a 100% accurate, physical .zenzic-vsm.json dump directly from the Docusaurus lifecycle, completely eliminating heuristic constraints.