# Backstage’s Zensical Engine Opens a Safer TechDocs Migration Path

- Link: https://thestackobserver.com/backstages-zensical-engine-opens-a-safer-techdocs-migration-path/
- Published: 2026-11-12T10:01:01-05:00
- Author: Stackxx

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 `palette` and `custom_dir`
   so 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.mkdocs` apply
   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.

## Sources

 * [Backstage documentation: Zensical Engine](https://backstage.io/docs/features/techdocs/engines-zensical/)
 * [Backstage 1.56.0 release notes: TechDocs engine abstraction](https://backstage.io/docs/releases/v1.56.0/)
 * [Backstage 1.56.3 release](https://github.com/backstage/backstage/releases/tag/v1.56.3)
 * [Zensical November update and Material for MkDocs maintenance extension](https://zensical.org/upcoming-changes/)
