[Docs] Replace MkDocs with Zensical #1522

stichbury · 2025-12-10T18:09:45Z

Closes https://github.com/McK-Internal/vizro-internal/issues/2316 by transitioning Vizro, Vizro-MCP and Vizro-AI docs over from MkDocs to Zensical.

Description

Ready for review! You can see the builds on RtD:

While I have created a new zensical.toml file (rather than just use the existing mkdocs.yml) we have had to revert to use the mkdocs.yml for now because of an issue with PyCafe. I will update as soon as the fix is in place from Zensical because using the toml format means we can pick up new features as they're added.

The settings are almost identical, but I added the feature header.autohide to increase viewport when scrolling down the page and added the feature navigation.path for breadcrumbs. We also now have light/dark theme support.

Issues

(a) There are some unsupported settings which we used -- like strict building. I think this is important but it's not here, so that means we could break an internal link and it won't be flagged. That's not ideal IMO but we may be able to catch these with a linkchecker instead, and it's in the backlog for Zensical to provide it.

(b) ~~PyCafe isn't working at present but I have identified the reason (probably) and raised an issue~~. Resolved by using mkdocs.yml while awaiting fix for the issue.

(c) ~~The llms-md buttons aren't working at present and that's another priority to investigate~~. Now fixed

Screenshot

Notice

I acknowledge and agree that, by checking this box and clicking "Submit Pull Request":
- I submit this contribution under the Apache 2.0 license and represent that I am entitled to do so on behalf of myself, my employer, or relevant third parties, as applicable.
- I certify that (a) this contribution is my original creation and / or (b) to the extent it is not my original creation, I am authorized to submit this contribution on behalf of the original creator(s) or their licensees.
- I certify that the use of this contribution as authorized by the Apache 2.0 license does not violate the intellectual property rights of anyone else.
- I have not referenced individuals, products or companies in any commits, directly or indirectly.
- I have not added data or restricted code in any commits, directly or indirectly.

This reverts commit 17ef196.

for more information, see https://pre-commit.ci

github-actions · 2025-12-10T18:12:00Z

View the example dashboards of the current commit live on PyCafe ☕ 🚀

Updated on: 2025-12-18 15:05:04 UTC
Commit: a8b5216

Compare the examples using the commit's wheel file vs the latest released version:

…izro into docs/zensical-rollout

for more information, see https://pre-commit.ci

…izro into docs/zensical-rollout

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

huong-li-nguyen

I mostly looked at the rendered docs, they look fine 👍

vizro-ai/mkdocs.yml

vizro-core/mkdocs.yml

vizro-core/zensical.toml.backup

Co-authored-by: Li Nguyen <[email protected]>

petar-qb

First of all, I’m impressed by how fast the documentation is built with Zensical!! 🚀

@stichbury, huge thanks for such a quick and smooth migration to Zensical. Really impressive work 🥇 ❤️

I’m not an expert when it comes to documentation tooling and yml/toml files behind it, so this is a humble, high-level review. That said, the docs definitely look and feel better, especially the search experience, and the build times are noticeably faster.

Zensical is still quite new, but it already shows a lot of promise and will likely evolve faster than our previous mkdocs setup.

vizro-ai/mkdocs.yml

vizro-ai/hatch.toml

vizro-core/hatch.toml

vizro-mcp/hatch.toml

vizro-core/mkdocs.yml

vizro-core/zensical.toml.backup

maxschulz-COL

I definitely see some issues in the rendered docs (atm checking on RtD) - see below:

maxschulz-COL · 2025-12-18T09:20:52Z

vizro-core/hatch.toml

 pip = '"{env:HATCH_UV}" pip {args}'
 pycafe-links = "../tools/pycafe/docs_links_filtering.sh"
-serve = "mkdocs serve --open {args}"
+serve = "zensical serve --open"


I naively tried to run this locally, and it gives me the following error:

hatch run docs:serve Serving /Users/Maximilian_Schulz/Documents_no_backup/Python/Vizro/vizro/vizro-core/site on http://localhost:8000 Build started Error: AttributeError: Failed to initiate extension 'mkdocstrings': module 'mkdocstrings' has no attribute 'makeExtension

You will be able to run locally but still need the mkdocstrings package as a dependency.

What does that mean? Do I need to install it manually? Should this not work with the hatch command?

…rk but aren't rejected)

for more information, see https://pre-commit.ci

…izro into docs/zensical-rollout

stichbury · 2025-12-18T12:59:04Z

I definitely see some issues in the rendered docs (atm checking on RtD) - see below:

@maxschulz-COL My friend, Cursor, and I have worked on this. This is the analysis:

Zensical doesn't currently support the autorefs plugin, which is part of the mkdocstrings ecosystem in MkDocs. This plugin automatically resolves reference-style links like [vizro.models.Graph] to the correct API documentation URLs.
Since Zensical is still in early development (version 0.0.11), it hasn't yet implemented support for all MkDocs plugins, including autorefs.

I have prevailed on Cursor to make content changes across the docs to accommodate this issue, and they are all in a single commit.

See this page rebuilt now for example

maxschulz-COL

I think we are still not there, see comments

maxschulz-COL · 2025-12-18T09:24:07Z

vizro-core/mkdocs.yml

Many of the settings here are shuffled around, why is that? Makes it a little harder to review to see what is new and what just changed place

vizro-core/zensical.toml.backup

maxschulz-COL · 2025-12-18T13:29:20Z

vizro-core/hatch.toml

 pip = '"{env:HATCH_UV}" pip {args}'
 pycafe-links = "../tools/pycafe/docs_links_filtering.sh"
-serve = "mkdocs serve --open {args}"
+serve = "zensical serve --open"


What does that mean? Do I need to install it manually? Should this not work with the hatch command?

vizro-core/zensical.toml.backup

maxschulz-COL · 2025-12-18T13:38:42Z

vizro-core/docs/pages/user-guides/graph-table-actions.md

I found some more occurences. These originate from the docstrings itself. This was found by just clicking around..

maxschulz-COL · 2025-12-18T13:40:28Z

vizro-ai/mkdocs.yml


-# Strictest settings possible, and will be elevated to ERROR when run with --strict.
-# See https://www.mkdocs.org/user-guide/configuration/#validation.
+# Keep these for now as strict building will be enabled by Zensical soon


Should we not also keep the old comment?

I don't think we need it -- we aren't explaining all the other settings in the file and some of those are far less evident from their naming.

This reverts commit e607881.

stichbury · 2025-12-18T15:06:29Z

Setting this PR aside for now.

Note that I reverted this commit (e6078819773f90d740f0172d37668669eb0d646b) to deal with the fact that autorefs is not supported. It means that API refdocs aren't correctly linked, but we should ideally hold out for that support to be added before we adopt Zensical.

The other ideals would be:

Python 3.14 support
kwds argument support for superfences so that we can use the .toml file to specify our docs build and still enable PyCafe linking
strict building and other validation

stichbury added 14 commits December 9, 2025 13:54

zensical

d1e9277

comment out in mkdocs

17ef196

Update zensical.toml

ad498f7

Remove folder

3c7ec19

Create zensical.toml

d7c488e

Update zensical.toml

a4a5fde

Update zensical.toml

9086a6f

Revert "comment out in mkdocs"

7e2f271

This reverts commit 17ef196.

Update hatch.toml

05b7ea4

Create favicon.png

0bfefa9

Update zensical.toml

b26d820

Update zensical.toml

9b181de

Update hatch.toml

cd9750e

Delete mkdocs.yml

044f186

stichbury self-assigned this Dec 10, 2025

Copilot AI review requested due to automatic review settings December 10, 2025 18:09

stichbury requested review from Joseph-Perkins, antonymilne, huong-li-nguyen, lingyielia and maxschulz-COL as code owners December 10, 2025 18:09

stichbury added the Docs 🗒️ Issue for markdown and API documentation label Dec 10, 2025

Copilot started reviewing on behalf of stichbury December 10, 2025 18:10 View session

[pre-commit.ci] auto fixes from pre-commit.com hooks

77b3f30

for more information, see https://pre-commit.ci

This comment was marked as resolved.

Sign in to view

stichbury and others added 4 commits December 10, 2025 18:32

Update zensical.toml

e385800

Merge branch 'docs/zensical-rollout' of https://github.com/mckinsey/v…

a380709

…izro into docs/zensical-rollout

Update zensical.toml

19361dc

[pre-commit.ci] auto fixes from pre-commit.com hooks

dd75234

for more information, see https://pre-commit.ci

github-actions bot added the Vizro-AI 🤖 Issue/PR that addresses Vizro-AI package label Dec 15, 2025

pre-commit-ci bot and others added 3 commits December 15, 2025 17:07

[pre-commit.ci] auto fixes from pre-commit.com hooks

f4b63c1

for more information, see https://pre-commit.ci

Further update for build tools

b7f58b7

Merge branch 'docs/zensical-rollout' of https://github.com/mckinsey/v…

b97d328

…izro into docs/zensical-rollout

stichbury requested review from Copilot, nadijagraca and petar-qb December 15, 2025 17:18

Copilot AI reviewed Dec 15, 2025

View reviewed changes

huong-li-nguyen approved these changes Dec 18, 2025

View reviewed changes

vizro-ai/mkdocs.yml Outdated Show resolved Hide resolved

vizro-core/mkdocs.yml Outdated Show resolved Hide resolved

vizro-core/zensical.toml.backup Outdated Show resolved Hide resolved

vizro-core/zensical.toml.backup Show resolved Hide resolved

stichbury and others added 2 commits December 18, 2025 08:57

Update vizro-core/zensical.toml.backup

3b5c735

Co-authored-by: Li Nguyen <[email protected]>

Merge branch 'main' into docs/zensical-rollout

0eda053

petar-qb approved these changes Dec 18, 2025

View reviewed changes

maxschulz-COL requested changes Dec 18, 2025

View reviewed changes

maxschulz-COL reviewed Dec 18, 2025

View reviewed changes

stichbury and others added 7 commits December 18, 2025 12:15

Add args back to zensical serve in hatch

c40aa1a

Comment for strict build flags and re-enable for yml builds (don't wo…

9b2fa82

…rk but aren't rejected)

Merge notifications addition to mkdocs.yml

feadb5f

Merge branch 'main' into docs/zensical-rollout

5bf9c0b

[pre-commit.ci] auto fixes from pre-commit.com hooks

74c1a3f

for more information, see https://pre-commit.ci

Fix broken API refs

e607881

Merge branch 'docs/zensical-rollout' of https://github.com/mckinsey/v…

081710a

…izro into docs/zensical-rollout

stichbury requested a review from maxschulz-COL December 18, 2025 12:59

maxschulz-COL requested changes Dec 18, 2025

View reviewed changes

stichbury added 4 commits December 18, 2025 14:39

Update mkdocs.yml

0ace44f

Update mkdocs.yml

8ea79fb

Revert "Fix broken API refs"

9fedb6b

This reverts commit e607881.

Update custom-components.md

a8b5216

stichbury closed this Dec 18, 2025

[Docs] Replace MkDocs with Zensical #1522

[Docs] Replace MkDocs with Zensical #1522

Uh oh!

Conversation

stichbury commented Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Issues

Screenshot

Notice

Uh oh!

github-actions bot commented Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

View the example dashboards of the current commit live on PyCafe ☕ 🚀

vizro-core/examples/scratch_dev

vizro-core/examples/dev/

vizro-core/examples/visual-vocabulary/

vizro-core/examples/tutorial/

Uh oh!

This comment was marked as resolved.

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

huong-li-nguyen left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

petar-qb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

maxschulz-COL left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stichbury commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

maxschulz-COL left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stichbury commented Dec 18, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

stichbury commented Dec 10, 2025 •

edited

Loading

github-actions bot commented Dec 10, 2025 •

edited

Loading

stichbury commented Dec 18, 2025 •

edited

Loading