Skip to content

Tooling consideration for docs site #58

@thompsonmj

Description

@thompsonmj

Building/serving a mkdocs site with Material recently yields message:

 │ ⚠ WARNING – MkDocs 2.0 is incompatible with Material for MkDocs
 │
 │   MkDocs 1.x is unmaintained. We recommend switching to Zensical, our
 │   new static site generator, as soon as possible. We're providing an
 │   analysis of the situation in this article:
 │
 │   https://squidfunk.github.io/mkdocs-material/blog/2026/02/18/mkdocs-2.0/

The linked summary page in the warning promotes Zensical as their suggested migration/continuity approach.

Presently, it seems like the following options are on the table for consideration among:

  1. Pin mkdocs and Material dependencies accordingly.
  2. Migrate to Zensical.
  3. Adopt mkdocs 2.0 with another theme.

Currently, I believe starting with 1) and phasing to 2) is reasonable for least friction and ideal long-term support. Discussion welcome!

Metadata

Metadata

Assignees

No one assigned

    Labels

    questionFurther information is requested

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions