[Docs] Replace MkDocs with Zensical

.gitignore

@@ -88,6 +88,7 @@ instance/
 # mkdocs
 vizro-core/site
 vizro-ai/site
+Vizro-mcp/site
 
 # PyBuilder
 .pybuilder/

vizro-ai/hatch.toml

@@ -62,8 +62,7 @@ test-unit-coverage = [
 
 [envs.docs]
 dependencies = [
-  "mkdocs>=1.6",
-  "mkdocs-material",
+  "zensical",
   "mkdocs-git-revision-date-localized-plugin>=1.2.5",
   "mkdocstrings[python]",
   "linkchecker",
@@ -75,14 +74,14 @@ detached = true
 installer = "uv"
 
 [envs.docs.scripts]
-build = "mkdocs build --strict"
+build = "zensical build --clean"
 # Disable warnings on the linkcheck so that HTTP redirects are accepted. We could ignore only that warning and specify
 # more advanced settings using a linkcheckerrc config file. openai.com doesn't seem to work well with linkchecking,
 # throwing 403 errors, but these are not real errors.
 link-check = "linkchecker site --check-extern --no-warnings --ignore=404.html --ignore-url=127.0.0.1 --ignore-url=https://vizro.readthedocs.io/ --ignore-url=https://platform.openai.com/docs/models --ignore-url=openai.com --ignore-url=https://openai.com/"
 pip = '"{env:HATCH_UV}" pip {args}'
 pycafe-links = "../tools/pycafe/docs_links_filtering.sh"
-serve = "mkdocs serve --open"
+serve = "zensical serve --open {args}"
 
 [envs.lower-bounds]
 extra-dependencies = ["pydantic==2.11.9"]  # required by langchain>=0.3.0 and openai>=1.108.0

vizro-ai/mkdocs.yml

@@ -1,5 +1,7 @@
 site_name: Vizro-AI
 site_url: https://vizro.readthedocs.io/projects/vizro-ai
+site_dir: site
+docs_dir: docs
 nav:
   - Vizro-AI: index.md
   - Tutorials:
@@ -39,9 +41,17 @@ repo_name: mckinsey/vizro-ai
 
 theme:
   name: material
+  variant: classic
   language: en
   palette:
     - scheme: default
+      toggle:
+        icon: lucide/sun
+        name: Switch to dark mode
+    - scheme: slate
+      toggle:
+        icon: lucide/moon
+        name: Switch to light mode
   font:
     text: Google sans
     code: Source Code Pro
@@ -122,8 +132,7 @@ hooks:
 extra_css:
   - stylesheets/extra.css
 
-# 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
 validation:
   omitted_files: warn
   absolute_links: warn

vizro-core/docs/pages/user-guides/custom-components.md

@@ -156,7 +156,7 @@ vm.Parameter.add_type("selector", TooltipNonCrossRangeSlider)
 
 You may want to use this strategy to:
 
-- Create a new component that does not exist as a [built-ninVizro model][vizro.models].
+- Create a new component that does not exist as a [built-in Vizro model][vizro.models].
 - Make extensive changes to an existing component.
 - Combine multiple components into a single higher-level component, similar to a Dash [All-in-One component](https://dash.plotly.com/all-in-one-components).
 

vizro-core/hatch.toml

@@ -115,15 +115,12 @@ test-unit-coverage = [
 
 [envs.docs]
 dependencies = [
-  "mkdocs>=1.6",
-  "mkdocs-material",
+  "zensical",
   "mkdocs-git-revision-date-localized-plugin>=1.2.5",
   "mkdocstrings[python]",
   "griffe-warnings-deprecated",
-  "mkdocs-llmstxt-md",
   "mkdocs-llmstxt>=0.5.0",
   "linkchecker",
-  "mkdocs-open-in-new-tab",
   "mkdocs-pycafe",
   "PyGithub",
   "playwright"
@@ -132,15 +129,15 @@ installer = "uv"
 template = "docs"  # Can't be detached = true since griffe_extensions:DynamicallyInspect needs vizro to be importable.
 
 [envs.docs.scripts]
-build = "mkdocs build --strict"
+build = "zensical build --clean"
 # Disable warnings on the linkcheck so that HTTP redirects are accepted. We could ignore only that warning and specify
 # more advanced settings using a linkcheckerrc config file.
 link-check = "linkchecker site --check-extern --no-warnings --ignore=404.html --ignore-url=127.0.0.1 --ignore-url=https://vizro.readthedocs.io/ --ignore-url=https://platform.ploomber.io/register --ignore-url=https://huggingface.co/join --ignore-url=https://www.ag-grid.com/"
 # Check if link to QB logo is not deleted from the docs.
 logo-check = "grep -q 'logo_watermark_extended.svg' docs/pages/user-guides/install.md"
 pip = '"{env:HATCH_UV}" pip {args}'
 pycafe-links = "../tools/pycafe/docs_links_filtering.sh"
-serve = "mkdocs serve --open {args}"
+serve = "zensical serve --open {args}"
 
 [envs.examples]
 # TODO: once the visual-vocabulary dashboard has moved out of this repo, this environment should be removed fully and

vizro-core/mkdocs.yml

@@ -1,7 +1,12 @@
 site_name: Vizro
 site_url: https://vizro.readthedocs.io/en/stable/
+site_description: Core Vizro documentation
+site_dir: site
+docs_dir: docs
+use_directory_urls: true
+
+# Make sure any new page added here is also added to the llmstxt plugin below
 nav:
-  # Make sure any new page added here is also added to the llmstxt plugin below (around line 156)
   - Vizro: index.md
   - Tutorials:
       - Quickstart tutorial: pages/tutorials/quickstart-tutorial.md
@@ -79,14 +84,25 @@ theme:
   name: material
   language: en
   custom_dir: docs/overrides
+  variant: classic
+  favicon: assets/images/favicon.png
   palette:
     - scheme: default
+      toggle:
+        icon: lucide/sun
+        name: Switch to dark mode
+    - scheme: slate
+      toggle:
+        icon: lucide/moon
+        name: Switch to light mode
   font:
     text: Google sans
     code: Source Code Pro
   icon:
     repo: fontawesome/brands/github
   features:
+    - header.autohide
+    - navigation.path
     - navigation.expand
     - navigation.instant
     - navigation.indexes
@@ -100,9 +116,6 @@ theme:
     - content.code.copy
     - content.code.annotate
 
-watch:
-  - src
-
 markdown_extensions:
   - pymdownx.highlight:
       anchor_linenums: true
@@ -133,14 +146,14 @@ markdown_extensions:
   - md_in_html
   - attr_list
   - pymdownx.emoji:
-      emoji_index: !!python/name:material.extensions.emoji.twemoji
-      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+      emoji_index: !!python/name:zensical.extensions.emoji.twemoji
+      emoji_generator: !!python/name:zensical.extensions.emoji.to_svg
 
 plugins:
   - search
   - autorefs
-  - llmstxt: # https://pypi.org/project/mkdocs-llmstxt/
-      markdown_description:
+  - llmstxt:
+      markdown_description: |
         Vizro is an open-source Python-based toolkit to build data visualization apps.
 
         Every Vizro app is defined by a simple configuration, using the high-level categories
@@ -214,12 +227,11 @@ plugins:
         python:
           options:
             show_bases: false
-            show_source: false #currently doesn't show source at correct level, and not for pydantic models
+            show_source: false
             docstring_style: google
             merge_init_into_class: true
             docstring_section_style: list
             separate_signature: true
-            #   filters: ["!^_"]
             show_root_heading: true
             docstring_options:
               ignore_init_summary: true
@@ -241,9 +253,9 @@ extra:
     - name: google-site-verification
       content: "CYb3cxosCgsN2QDQVaSGQpMQCesqpsGQ3oTM02NtvkY"
 extra_css:
-  - stylesheets/extra.css
+  - /stylesheets/extra.css
 extra_javascript:
-  - javascripts/extra.js
+  - /javascripts/extra.js
 # Strictest settings possible, and will be elevated to ERROR when run with --strict.
 # See https://www.mkdocs.org/user-guide/configuration/#validation.
 validation: