Imageomics / Imageomics/Collaborative-distributed-science-guide
Tooling consideration for docs site
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1
- Forks
- 1
- PR merge metrics
- No merged PRs in 30d
Description
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:
- Pin mkdocs and Material dependencies accordingly.
- Migrate to Zensical.
- 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!
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
No repository files or entry points are named. Start by locating the current MkDocs and Material dependency configuration and the commands used to build or serve the site, then compare the three options against the linked migration guidance. Done should mean that one approach is selected, documented, and verified with a successful site build.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation, tooling
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100