📜 Issue Labels
🔎 Search Terms
mkdocs for material in maintenance mode
🗃️ Project Area
TechDocs
🛠️ Task
Motivation
First, I want to share how much we value the federated documentation model that TechDocs enables. The ability to treat documentation as code, decentralized across teams while remaining centrally discoverable, is one of the killer features of Backstage. It has fundamentally changed how we think about knowledge sharing.
However, as we evaluate and commit to TechDocs as our long-term technical documentation solution, the sustainability of the underlying engine is becoming a significant concern. To ensure the longevity and stability of the platform, I would like to understand how the Backstage ecosystem plans to navigate the shifting landscape of MkDocs and its primary theme, mkdocs-material.
Context
The current TechDocs implementation is deeply coupled with the MkDocs ecosystem. Two recent trends have caught my attention:
Sustainability of mkdocs-material: The creator of mkdocs-material recently published a blog post (The future of MkDocs Material) highlighting the challenges of maintaining the project and introducing Zensical (https://zensical.org/) as a potential successor.
Upstream Maintenance: Maintenance on the core mkdocs repository appears to have slowed significantly. In the past year, I have observed very few code commits and a growing backlog of unaddressed issues and PRs.
Discussion Points
I would love to get the maintainers and the community perspective on the following:
-
Is the TechDocs or the core maintainer team currently tracking the pivot from mkdocs-material toward Zensical?
-
If Zensical (or another engine) becomes the industry recommendation, are there early thoughts on supporting it as a first-class citizen within the TechDocs container and techdocs-cli?
-
Does this trend accelerate the need for TechDocs to become more "engine-agnostic," allowing easier plug-and-play for builders beyond the standard MkDocs implementation?
We want to keep the momentum behind TechDocs strong, and clarity here will help us onboard to the platform. I appreciate your help
📊 Priority & Impact
Medium/High (Strategic) While this is not a breaking bug in the current release, it represents a significant architectural risk. As we are currently in the evaluation and onboarding phase for TechDocs at scale, the uncertainty regarding the underlying build engine creates a hurdle for our internal adoption.
With the upstream project being maintained only till end of 2026, it might be ideal to discuss this topic now so the team and the community have enough time to address this issue.
Have you read the Code of Conduct?
Are you willing to submit a PR?
Yes, but I would like some more guidance
📜 Issue Labels
🔎 Search Terms
🗃️ Project Area
TechDocs
🛠️ Task
Motivation
First, I want to share how much we value the federated documentation model that TechDocs enables. The ability to treat documentation as code, decentralized across teams while remaining centrally discoverable, is one of the killer features of Backstage. It has fundamentally changed how we think about knowledge sharing.
However, as we evaluate and commit to TechDocs as our long-term technical documentation solution, the sustainability of the underlying engine is becoming a significant concern. To ensure the longevity and stability of the platform, I would like to understand how the Backstage ecosystem plans to navigate the shifting landscape of MkDocs and its primary theme, mkdocs-material.
Context
The current TechDocs implementation is deeply coupled with the MkDocs ecosystem. Two recent trends have caught my attention:
Sustainability of mkdocs-material: The creator of mkdocs-material recently published a blog post (The future of MkDocs Material) highlighting the challenges of maintaining the project and introducing Zensical (https://zensical.org/) as a potential successor.
Upstream Maintenance: Maintenance on the core mkdocs repository appears to have slowed significantly. In the past year, I have observed very few code commits and a growing backlog of unaddressed issues and PRs.
Discussion Points
I would love to get the maintainers and the community perspective on the following:
Is the TechDocs or the core maintainer team currently tracking the pivot from mkdocs-material toward Zensical?
If Zensical (or another engine) becomes the industry recommendation, are there early thoughts on supporting it as a first-class citizen within the TechDocs container and techdocs-cli?
Does this trend accelerate the need for TechDocs to become more "engine-agnostic," allowing easier plug-and-play for builders beyond the standard MkDocs implementation?
We want to keep the momentum behind TechDocs strong, and clarity here will help us onboard to the platform. I appreciate your help
📊 Priority & Impact
Medium/High (Strategic) While this is not a breaking bug in the current release, it represents a significant architectural risk. As we are currently in the evaluation and onboarding phase for TechDocs at scale, the uncertainty regarding the underlying build engine creates a hurdle for our internal adoption.
With the upstream project being maintained only till end of 2026, it might be ideal to discuss this topic now so the team and the community have enough time to address this issue.
Have you read the Code of Conduct?
Are you willing to submit a PR?
Yes, but I would like some more guidance