Running Tailwind CSS components inside a MkDocs Material documentation site introduces a deceptively subtle conflict. This post documents the architectural decision, the failure mode it resolves, and why we chose a pure-CSS solution over the obvious alternatives.
We spent a full development cycle building a Docusaurus adapter for Zenzic. We ran forensic audits on real Docusaurus projects. Then we deleted every line of it.
To validate the parser and snippet-analysis capabilities of Zenzic, we needed a production-grade documentation corpus. We selected the official documentation repository of Zensical, a mature and actively maintained static site generator.
The expectation was straightforward: a well-maintained documentation codebase should produce few, if any, actionable findings.
Instead, the scan surfaced a small set of defects that had survived normal review processes. None were catastrophic, but all had user-facing consequences ranging from copy-paste failures to broken navigation and accessibility regressions.
This article examines the findings and explores why documentation quality often requires deeper analysis than conventional Markdown validation.
Zenzic v0.10.0 introduces a massive performance upgrade with a new Async Network Engine, alongside two architectural changes designed strictly for the CI/CD pipeline: Native GitHub Annotations and Destructive Rule Filtering.
These features are not aesthetic. They are built to solve three specific operational bottlenecks: network-induced CI flakiness, context switching during Pull Request reviews, and the high friction of adopting static analysis in legacy documentation repositories.
In modern CI/CD pipelines, security and performance should be structurally bounded, not just empirically observed. Traditional documentation linters and credential scanners often fail when operating at scale or under adversarial conditions. The primary failure mode is ReDoS (Regular Expression Denial of Service).
v0.9.0 establishes deterministic telemetry as a release-level engineering contract across core, action, and docs.
Zenzic is designed to run inside automated pipelines without configuration drift. On the v0.9.0 line, three patterns appear consistently in production deployments: a quality gate that blocks merges on score regression, a containment strategy for repositories with accumulated link debt, and an i18n parity gate enforcing structural symmetry across translations.
These patterns target different teams at different stages: DevOps teams enforcing merge gates in CI, technical leads scoping governance adoption in repositories with accumulated debt, and documentation engineers maintaining multilingual portals. The patterns are independent and can be combined. A repository with legacy debt can run Pattern 2 to fence exemptions while still enforcing a quality floor via Pattern 1 and structural i18n parity via Pattern 3.
A linter reports violations within individual files. A governance engine verifies that a set of invariants holds across the entire document graph — and halts the pipeline when one does not.
This analysis reflects the terminal contract as shipped on the v0.9.0 release line.
The Documentation Quality Score (DQS) is an integer from 0 to 100. Given the same repository state, it always produces the same number. v0.8.0 changed two things: it closed a gate paradox where CI-blocking codes had zero DQS weight, and it replaced the allowance-based suppression model with a flat-cost model.
Zenzic emerged as a systems response to a recurring pattern across code reviews and CI incidents: documentation quality pipelines were improving locally but degrading structurally over time. The pipeline was shipping checks, not guarantees — collecting signals, not preserving architecture.