Backstage has added an experimental Zensical engine to TechDocs, giving platform teams a practical way to test the successor to Material for MkDocs without changing every documentation site at once. That matters because the migration deadline has moved, but the underlying platform decision has not disappeared: Material for MkDocs now receives critical maintenance through May 5, 2027, while its creators are concentrating new development on Zensical.
The right response is not an emergency fleet-wide switch. It is a controlled compatibility program. Backstage’s engine abstraction and per-entity annotation let a platform team run Zensical against selected TechDocs sites while MkDocs remains the default. The six-month extension should therefore be treated as a testing window, not permission to leave the problem until spring.
Backstage now has a migration control plane
Backstage 1.56.0 introduced the architectural piece that makes a gradual transition possible: a TechDocs engine abstraction. It added an engine registry, an engine field in generated metadata, an --engine option in the TechDocs CLI, and the backstage.io/techdocs-engine catalog annotation. MkDocs remained the default, so upgrading Backstage did not itself alter documentation output.
Backstage 1.56.3 then supplied an experimental Zensical implementation through @backstage/plugin-techdocs-backend-module-zensical. The module can be registered alongside the existing TechDocs backend. Teams can opt in a single catalog entity with backstage.io/techdocs-engine: zensical, while all unannotated entities continue using MkDocs. A global techdocs.generator.defaultEngine setting is available, but it should come late in a rollout, not at the start.
This separation is the most useful feature of the release. A documentation engine migration touches content maintained by many teams, but the platform group does not have to coordinate a flag day. Engine choice becomes catalog metadata that can be applied, observed, and reversed at the boundary of each service.
Zensical also reads the same mkdocs.yml file and docs/ directory used by current TechDocs projects. That lowers the cost of a trial because teams need not reorganize their source tree merely to compare engines. It does not guarantee identical output, however, and Backstage explicitly labels the integration experimental and subject to changes in minor releases.
The deadline moved, but the risk merely changed shape
Zensical 0.1.0 became available on November 5. On the same day, its maintainers extended critical maintenance for Material for MkDocs by six months, from the previously announced November date to May 5, 2027. They describe the extension as time for organizations to evaluate the migration path, test existing projects, and plan a controlled production transition.
That is an important correction to the timing reflected in Backstage 1.56.3’s release note, which referred to Material for MkDocs shutting down on November 5. The project did not abruptly vanish: packages and repositories remain available, and critical maintenance continues during the extension. Platform teams should update internal risk registers and migration tickets with the new date.
They should not close those tickets. Zensical is now on a dependable 0.1 release line, but its maintainers say public APIs will continue to evolve while the module system and ecosystem mature. Meanwhile, Backstage’s adapter has known behavioral differences and is itself experimental. The extra time reduces deadline pressure, while increasing the value of gathering evidence before either project’s interfaces settle further.
What is compatible—and what is not
Backstage does more than invoke a different binary. MkDocs builds traditionally depend on the techdocs-core plugin, which Zensical cannot load. For Zensical builds, TechDocs instead creates a temporary copy of mkdocs.yml, injects relevant Markdown extensions, configures the Material theme, removes techdocs-core, and converts search output into the format expected by the TechDocs search collator.
That translation layer preserves important platform behavior, including TechDocs search and familiar Markdown features such as admonitions, tabs, snippets, and PlantUML. It also enforces restrict_base_path: true for snippets so documents cannot include files from outside the project. But several differences deserve explicit tests:
- Navigation and theme configuration: TechDocs removes
paletteandcustom_dirso the Backstage frontend controls light and dark modes. It retains other theme settings and adds footer navigation. - Plugin compatibility: a repository that relies on MkDocs plugins or custom Markdown extensions may build differently or fail under Zensical. A successful basic site is not evidence that the long tail is compatible.
- Edit links: Backstage documents that “Edit this page” does not yet work for Zensical builds because the required repository URL and edit path are not set.
- Configuration scope: some settings under
techdocs.generator.mkdocsapply to both engines, including the allowlists for additional keys and plugins. Relaxing those controls for one engine relaxes them for the other. - Runtime packaging: Docker deployments need a Zensical-specific image setting. A custom MkDocs image does not automatically carry over, and local execution requires Zensical plus the extensions enabled by TechDocs.
These are exactly the sorts of details that make a canary rollout preferable to a global default change. Compatibility is not a single yes-or-no property; it is a distribution across the documentation patterns used in an organization.
A four-stage rollout for platform teams
1. Inventory the documentation fleet
Start by querying catalog entities that publish TechDocs and grouping them by risk. Identify custom plugins, nonstandard theme overrides, snippets, diagrams, large search indexes, strict build-time requirements, and critical operational runbooks. Include repositories that build documentation centrally and those that generate it in CI, because the runtime and ownership boundaries differ.
Choose canaries that are representative, not merely simple. A useful initial cohort might include one plain Markdown site, one site with diagrams, one with extensive navigation, and one with approved custom extensions. Avoid starting with the organization’s most critical incident manual, but make sure at least one canary exercises every feature that could block broader adoption.
2. Establish a reproducible test environment
Install the Zensical backend module and register it beside the TechDocs backend. If builds run in Docker, use the pinned image provided by Backstage or pin an explicit release tag; do not use latest. An unpinned generator makes regressions difficult to reproduce and can cause two builds of unchanged source to differ.
Keep MkDocs as the default. Developers can first run techdocs-cli serve --engine zensical or techdocs-cli generate --engine zensical locally. Once a repository passes local checks, add the per-entity engine annotation and observe the same workload in the shared Backstage environment.
3. Compare outcomes, not just exit codes
A green build is necessary but insufficient. Capture build duration, CPU and memory consumption, output size, warning counts, and failure categories for both engines. Then validate the reader experience: navigation order, anchors, code highlighting, diagrams, admonitions, search results, internal links, external links, and light/dark presentation.
Use rendered-page snapshots or a link checker where practical, but retain human review for critical pages. Search deserves its own acceptance test because Backstage converts Zensical’s output for the existing collator. Define sample queries and expected top results before the trial, then compare relevance and indexing latency across engines.
Record known gaps separately from defects. For example, the missing edit-page link is a documented limitation, so the decision is whether teams can temporarily tolerate it or need a replacement workflow. A broken custom plugin is instead a compatibility blocker requiring configuration changes, upstream support, or an explicit decision to retire the plugin.
4. Expand by policy, then change the default
After representative canaries meet the acceptance criteria, expand by service tier or documentation pattern. Publish a lightweight readiness checklist and let service owners request the annotation through their normal catalog review. Maintain an immediate rollback path: removing the Zensical annotation returns an entity to the MkDocs default without restructuring its content.
Only change defaultEngine after the exception list is smaller than the migrated population and the platform team has operational confidence in the new image, configuration, and support process. Before that switch, explicitly annotate remaining exceptions with backstage.io/techdocs-engine: mkdocs. That converts silent dependence on the old default into visible, searchable technical debt.
Security and governance need their own acceptance criteria
The shared configuration allowlist deserves careful review. Backstage notes that dangerouslyAllowAdditionalKeys and dangerouslyAllowAdditionalPlugins apply to both MkDocs and Zensical even though they live under the MkDocs configuration tree. A trial should not broaden either list merely to make one repository pass. Every added plugin expands the code and configuration accepted by a shared build service.
Platform teams should also pin generator artifacts, scan the chosen container, retain build logs, and define who may select an engine through catalog metadata. If entity descriptors are broadly editable, engine selection becomes part of the build-input threat model. Existing repository review controls may be sufficient, but the assumption should be documented and tested.
The migration is also a chance to clarify support boundaries. Service teams own their content and repository-specific configuration; the platform team owns the approved engine versions, base images, shared allowlists, observability, and rollback mechanism. Without that division, every rendering discrepancy becomes an ambiguous platform incident.
Use the extension to buy evidence
Backstage’s Zensical support arrived at the right architectural layer. The engine abstraction makes documentation generation selectable per entity, and the shared source layout makes trials comparatively cheap. At the same time, the experimental label, configuration differences, and missing edit links argue against declaring the migration finished.
The May 2027 maintenance date gives organizations room to proceed methodically. A good outcome by early 2027 is not necessarily a completed fleet migration; it is a measured compatibility matrix, pinned and reproducible builds, a shrinking exception list, and a proven rollback path. Teams that use the runway that way will be able to change the default deliberately. Teams that read “six more months” as “come back later” will encounter the same uncertainty with less time to resolve it.


