a2ui-project / a2ui-project/a2ui

[docs] Replace `mkdocs` by `properdocs` ?

Open Beginner friendly
#1,458 2 comments 0 reactions 0 assignees View on GitHub
dependencies P2 size: small type: documentation
Dominant language
TypeScript
Stars
16.4k
Forks
1.3k
Avg merge
2d 13h
Merged PRs (30d)
134

Description

While testing a PR, I built the a2ui.org site with mkdocs, and got the following warning:

```console
(.venv) dit@dit:/work/google/a2ui$ mkdocs serve

│ ⚠ 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/

----------------------------------------------------------------

WARNING: MkDocs may break support for all existing plugins and themes soon!

The owner of MkDocs has completely abandoned maintenance of the project, and instead is
planning to publish a "version 2" which will not support any existing themes, plugins or even
your configuration files. This v2 may eventually replace what you download with `pip install
mkdocs`, suddenly breaking the build of your existing site.

To avoid these risks, switch to ProperDocs, a continuation of MkDocs 1.x and a drop-in
replacement that supports your current MkDocs setup.
Simply install it with `pip install properdocs` and build your site with `properdocs build`
instead of the MkDocs equivalents.

Alternatively, to just skip this warning in the future, you can set the environment variable
`DISABLE_MKDOCS_2_WARNING=true`.

For more info visit https://github.com/ProperDocs/properdocs/discussions/33 and
https://properdocs.org/

(This warning was initiated by one of the plugins that you depend on.)
```

I guess we need to migrate to ProperDocs?

Contributor guide

Open the contributing guide

Research direction

Look for the documentation build configuration, likely in mkdocs.yml or a similar file. Check the CI/CD configuration (e.g., GitHub Actions workflows) for commands like 'mkdocs build' or 'mkdocs serve'. Replace these with 'properdocs' commands and update any related scripts or documentation. Test the build locally to ensure the site generates correctly.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
build-system, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
70/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.