Skip to content

馃殌馃捇 鈥撀爐ransition to properdocs#276

Description

@botanize

Describe the feature you want and how it meets your needs or solves a problem

As a TIDES developer, I want documentation tools to continue to function so that I can make contributions to the project. Recently while running mkdocs --serve I came across this notice:

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/

Describe the solution you'd like
I'd like to replace the mkdocs dependency with properdocs and avoid unexpected incompatibilities in the future. As of version 2.2 mike defaults to properdocs if it's found and then falls back on mkdocs if not.

Describe alternatives you've considered
We could pin mkdocs to a version < 2.0 (currently 1.6.1). The downside is we may lose the ability to update mkdocs.

Additional context

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    馃捇 codePertains to the infrastructure code馃殌 featureAdds a new feature - to spec or code

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions