microsoft / microsoft/AzureTRE

MKDocs v1 is no longer maintained

Open
#5,006 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
235
Forks
192
Avg merge
1d 23h
Merged PRs (30d)
13

Description

Describe the bug
MKDocs v1 is unmaintained and v2 is being released with no plugin support

There are a few forks and drop in replacements, one of the MKDocs maintainers created ProperDocs which maintains compatibility.
https://github.com/orgs/ProperDocs/discussions/33

See also https://fpgmaas.com/blog/collapse-of-mkdocs/

The Material for MKDocs have also launched a documentation site zensical
https://squidfunk.github.io/mkdocs-material/blog/2026/02/18/mkdocs-2.0/

 │  ⚠  Warning from the Material for MkDocs team
 │
 │  MkDocs 2.0, the underlying framework of Material for MkDocs,
 │  will introduce backward-incompatible changes, including:
 │
 │  × All plugins will stop working – the plugin system has been removed
 │  × All theme overrides will break – the theming system has been rewritten
 │  × No migration path exists – existing projects cannot be upgraded
 │  × Closed contribution model – community members can't report bugs
 │  × Currently unlicensed – unsuitable for production use
 │
 │  Our full analysis:
 │
 │  https://squidfunk.github.io/mkdocs-material/blog/2026/02/18/mkdocs-2.0/

For now I'd suggest pinning mkdocs<2.0.0 and then considering alternatives

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

The issue names no files or tests; start by locating the repository's MkDocs dependency and configuration. Confirm how the project currently invokes MkDocs and identify the appropriate supported version constraint. Done means the dependency is safely pinned below 2.0.0 and the documentation build still works.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
build-system
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.