Migrate from MkDocs to Zensical

As you might have noticed, the MkDocs project released its latest version on GitHub on Friday, 30th August 2024. According to a discussion in their repository, the project is currently unmaintained. As far as I know, they are searching for trusted contributors who want to continue maintaining the project and fixing critical bugs.

Given this situation, I started looking for alternatives to migrate my various documentation projects to an actively maintained static site generator. Since I had almost always used Material for MkDocs on top of MkDocs, my choice was a new project called “Zensical”, created by the same developers behind Material for MkDocs.

From their blog post:

“With Zensical, we are creating a modern static site generator, which is compatible with your content and customizations, and addresses MkDocs’ limitations. While Material for MkDocs is built on top of MkDocs, Zensical consolidates both projects into one coherent stack, covering static site generation, theming, and customization.”

This project sounded very promising, and they even provide a migration guide for users coming from MkDocs.

Migrate to Zensical

The first thing I did was try to render all my .md-based documentation locally with Zensical. As promised, it worked exactly as described in their docs.

Running zensical build --clean produced the generated pages that I could then publish as an artifact to GitHub Pages.

Note: They support the classic mkdocs.yml files as a configuration file to ease the transition. However, you also can create a fresh zensical.toml file if you start out in a new project.

Speaking of GitHub Pages, the last remaining step was to update the workflow to publish my docs via GitHub Actions.

This was straightforward from this point on. A simplified example of this pipeline:

 1jobs:
 2  deploy:
 3    environment:
 4      name: github-pages
 5      url: ${{ steps.deployment.outputs.page_url }}
 6    runs-on: ubuntu-25.10
 7    steps:
 8      - uses: actions/configure-pages@v5
 9      - uses: actions/checkout@v5
10      - uses: actions/setup-python@v5
11        with:
12          python-version: 3.15
13      - name: Install uv
14        uses: astral-sh/setup-uv@v7
15      - run: uv tool install zensical
16      - run: zensical build --clean
17      - uses: actions/upload-pages-artifact@v4
18        with:
19          path: site
20      - uses: actions/deploy-pages@v4
21        id: deployment

The feeling when a pipeline succeeds on the first try after testing locally is unbelievably satisfying. With that, I had successfully migrated one of my public documentation to Zensical:

Sources

MkDocs project - https://github.com/mkdocs/mkdocs

MkDocs unmaintained status - https://github.com/mkdocs/mkdocs/discussions/4010

MkDocs Material - https://github.com/squidfunk/mkdocs-material

Zensical - https://zensical.org/

Zensical Basics - https://zensical.org/docs/setup/basics/

Zensical Announcement - https://squidfunk.github.io/mkdocs-material/blog/2025/11/05/zensical/