MetOffice / MetOffice/CDDS

Evaluate migrating to Zensical from material+mkdocs

Open
#794 0 comments 0 reactions 0 assignees View on GitHub
documentation
Dominant language
Python
Stars
8
Forks
7
Avg merge
1d 15h
Merged PRs (30d)
23

Description

The material for mkdocs theme is no longer under active development. Read why here https://squidfunk.github.io/mkdocs-material/blog/2025/11/05/zensical/#why-zensical

It looks like they are maintaining some amount of backwards compatibility and integrating some of the more popular plugin functionality.

I think the main things we'll to check are
- Versioning - Can we work in the same way as we do with `mike?` Can we carry over our old "built" docs on our `gh-pages` branch to this new solution?
- Plugins - Are we relying on plugin functionality that hasn't been reimplemented in Zensical?

https://zensical.org/

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the linked Zensical rationale and the project's current mike and plugin setup. Check whether versioning and existing built documentation on the gh-pages branch can be carried over, then compare each required plugin with Zensical's supported functionality. Done means a documented migration assessment, including compatibility gaps and open questions.

Written by the indexing model from the issue text.

Assessment

Domain
build-system, documentation, tooling
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.