Backstage TechDocs 2026: Zensical als Ausweichpfad vor dem Material-for-MkDocs-Ende

📷 "Technology Abstract" by Lenharth Systems is marked with CC0 1.0. To view the terms, visit https://creativecommons.org/publicdomain/zero/1.0/.

Am 2. November 2026 veröffentlichte das Backstage-Projekt die Version 1.56.3 – einen Vier-Tage-Patch, der auf den ersten Blick unscheinbar wirkt, aber eine der drängendsten Infrastrukturfragen für Plattform-Teams adressiert: Was passiert mit TechDocs, wenn Material for MkDocs verschwindet? Die Antwort heißt Zensical, und sie kommt als experimenteller Motor für die Dokumentations-Pipeline von Backstage.

Warum der Zeitpunkt kritisch ist

TechDocs ist die Dokumentations-Engine von Backstage und damit für viele Unternehmen der zentrale Ort, an dem Entwickler Service-Dokumentation, ADRs und Runbooks finden. Unter der Haube setzt TechDocs auf Material for MkDocs – ein weit verbreitetes Theme und Static-Site-Generator, das von Martin Donath (squidfunk) entwickelt wurde. Im November 2025 gab das Team bekannt, dass die aktive Entwicklung eingestellt wird und der Fokus auf dem Nachfolger Zensical liegt.

Ursprünglich war der 5. November 2026 als End-of-Life-Datum gesetzt. Im September 2026 wurde die Frist auf Mai 2027 verlängert, aber der implizite Druck auf Plattform-Teams blieb: Wer TechDocs in Produktion betreibt, muss mittelfristig umsteigen. Backstage hat diesen Umstieg nun mit Version 1.56.3 konkret gemacht.

Die TechDocs-Engine-Abstraktion als Fundament

Schon Backstage 1.56.0 (Oktober 2026) legte mit einer TechDocs-Engine-Abstraktion das Fundament: Statt MkDocs fest einzubinden, können nun verschiedene Generatoren eingesetzt werden. Die Abstraktion erlaubt es, den Build-Prozess von TechDocs auszutauschen, ohne die umliegende Pipeline (Preparing, Publishing, Serving) neu zu schreiben. Das ist die Voraussetzung für den Zensical-Support, der in 1.56.3 dann tatsächlich eingebaut wurde.

Was Backstage 1.56.3 konkret liefert

Der Release bringt drei Komponenten mit:

@backstage/plugin-techdocs-backend-module-zensical: Ein neues Backend-Modul, das Zensical als TechDocs-Engine integriert. Es wird als experimentell markiert – produktive Adoption ist möglich, aber mit erhöhter Vorsicht empfohlen.
CLI-Unterstützung: @techdocs/cli kann TechDocs-Projekte nun auch mit Zensical bauen. Das erlaubt es, lokal oder in CI-Pipelines gegen den neuen Generator zu testen.
Alpha-Bausteine in @backstage/plugin-techdocs-node: Für Teams mit benutzerdefinierten TechDocs-Pipelines stehen neue APIs bereit, die in die Zensical-Engine einbinden.

Die Maturitätsstufen sind bewusst gewählt: experimental (Backend-Modul) und alpha (Node-APIs) signalisieren, dass dieser Pfad getestet, aber noch nicht für jeden Produktionsfall abgesichert ist. Das Backstage-Projekt hat damit einen pragmatischen Mittelweg gewählt: schnell liefern, aber keine falsche Versprechung von Null-Aufwands-Migration machen.

Was Zensical ist – und was nicht

Zensical wird vom selben Team entwickelt wie Material for MkDocs. Es ist kein Fork, sondern eine Neuentwicklung, die – Stand November 2026 – die wichtigsten MkDocs-Features abdeckt: mkdocs.yml als Konfiguration, Python Markdown, die meisten Theme-Einstellungen und eine wachsende Zahl von Plugin-Replacements. Es versteht sich als kompatibel, aber nicht identisch. Wer benutzerdefinierte MkDocs-Plugins, Template-Overrides oder spezielle Theme-Anpassungen einsetzt, sollte vor der Migration gründlich testen.

Die offizielle Kompatibilitätsseite führt die unterstützten Settings und Plugins auf. Dort zeigt sich: für Standard-Dokumentationen ist der Umstieg meist reibungslos, für stark individualisierte Projekte ist eine Prüfung pro Plugin nötig.

Was Plattform-Teams jetzt tun sollten

Drei Schritte sind aus heutiger Sicht sinnvoll:

Testumgebung aufsetzen: Ein nicht-produktives Backstage auf 1.56.3 heben und repräsentative TechDocs-Projekte – inklusive solcher mit benutzerdefinierten Plugins und Themes – gegen die Zensical-Engine bauen. Die Unterschiede in Build-Logs und generierter Ausgabe dokumentieren.
Abhängigkeiten inventarisieren: Welche TechDocs-Projekte nutzen MkDocs-Plugins, die noch kein Zensical-Äquivalent haben? Besteht eine Abhängigkeit von MkDocs-Only-Features? Diese Liste ist die Grundlage für den Migrationsplan.
Golden Path anbieten: Statt jedes Team die Migration selbst organisieren zu lassen, sollte die Plattform einen geprüften Builder-Image mit aktiviertem Zensical-Modul, CI-Snippets und eine Rollout-Checkliste bereitstellen. Das senkt die kognitive Last für die Teams und verhindert Ad-hoc-Flickschusterei.

Die Frist bis Mai 2027 klingt großzügig – aber wer erst dann testet, hat das Zeitfenster für eine geordnete Migration verschenkt. Der experimentelle Status bedeutet nicht, dass die Engine nicht funktioniert, sondern dass sie sich noch ändern kann. Wer heute testet, ist gewappnet, wenn die Stabilisierung in einer der nächsten Versionen erfolgt.

Fazit

Backstage 1.56.3 ist ein wichtiger Meilenstein für die TechDocs-Zukunft. Die experimentelle Zensical-Integration gibt Plattform-Teams einen konkret testbaren Ausweg aus der Material-for-MkDocs-Abhängigkeit. Der Aufwand für die Migration ist überschaubar – vorausgesetzt, man beginnt jetzt mit der Evaluierung und baut sich ein reproduzierbares Test-Setup auf. Die nächsten Backstage-Versionen (1.57.x) werden die Alpha-APIs weiter stabilisieren; bis dahin gilt: Testen, dokumentieren, vorbereiten.