Closes #21635: Migrate from mkdocs to Zensical (#21742)

* Drop mkdocs from `requirements.txt` and add Zensical
* Replace mkdocs with Zensical in CI and pre-commit tasks
* Remove `.info` from the `docs/` build directory (obsolete)
* Update the legacy ReadTheDocs configuration
* Update upgrade script to use Zensical
* Remove custom docs footer
* Remove obsolete CSS

.github/workflows/ci.yml

@@ -92,7 +92,7 @@ jobs:
         pip install coverage tblib
 
     - name: Build documentation
-      run: mkdocs build
+      run: zensical build
 
     - name: Collect static files
       run: python netbox/manage.py collectstatic --no-input

.pre-commit-config.yaml

@@ -21,11 +21,11 @@ repos:
       language: system
       pass_filenames: false
       types: [python]
-    - id: mkdocs-build
+    - id: zensical-build
       name: "Build documentation"
-      description: "Build the documentation with mkdocs"
+      description: "Build the documentation with Zensical"
       files: 'docs/'
-      entry: mkdocs build
+      entry: zensical build
       language: system
       pass_filenames: false
     - id: yarn-validate

.readthedocs.yaml

@@ -1,10 +1,10 @@
 version: 2
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
     python: "3.12"
-mkdocs:
-  configuration: mkdocs.yml
-python:
-   install:
-   - requirements: requirements.txt
+  commands:
+    - pip install -r requirements.txt
+    - python -m zensical build --config-file mkdocs.yml
+    - mkdir -p $READTHEDOCS_OUTPUT/html/
+    - cp -r netbox/project-static/docs/* $READTHEDOCS_OUTPUT/html/

base_requirements.txt

@@ -101,10 +101,6 @@ jsonschema
 # https://python-markdown.github.io/changelog/
 Markdown
 
-# MkDocs
-# https://github.com/mkdocs/mkdocs/releases
-mkdocs<2.0
-
 # MkDocs Material theme (for documentation build)
 # https://squidfunk.github.io/mkdocs-material/changelog/
 mkdocs-material
@@ -178,3 +174,7 @@ tablib
 # Timezone data (required by django-timezone-field on Python 3.9+)
 # https://github.com/python/tzdata/blob/master/NEWS.md
 tzdata
+
+# Documentation builder (succeeds mkdocs)
+# https://github.com/zensical/zensical
+zensical

docs/_theme/partials/copyright.html

@@ -1,18 +0,0 @@
-<div class="md-copyright">
-  {% if config.copyright %}
-    <div class="md-copyright__highlight">
-      {{ config.copyright }}
-    </div>
-  {% endif %}
-  {% if not config.extra.generator == false %}
-    Made with
-    <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
-      Material for MkDocs
-    </a>
-  {% endif %}
-</div>
-{% if not config.extra.build_public %}
-  <div class="md-copyright">
-    ℹ️ Documentation is being served locally
-  </div>
-{% endif %}

docs/development/getting-started.md

@@ -97,7 +97,7 @@ NetBox uses [`pre-commit`](https://pre-commit.com/) to automatically validate co
 * Run the `ruff` Python linter
 * Run Django's internal system check
 * Check for missing database migrations
-* Validate any changes to the documentation with `mkdocs`
+* Validate any changes to the documentation with `zensical`
 * Validate Typescript & Sass styling with `yarn`
 * Ensure that any modified static front end assets have been recompiled
 

docs/development/release-checklist.md

@@ -47,7 +47,7 @@ If a new Django release is adopted or other major dependencies (Python, PostgreS
 Start the documentation server and navigate to the current version of the installation docs:
 
 ```no-highlight
-mkdocs serve
+zensical serve
 ```
 
 Follow these instructions to perform a new installation of NetBox in a temporary environment. This process must not be automated: The goal of this step is to catch any errors or omissions in the documentation and ensure that it is kept up to date for each release. Make any necessary changes to the documentation before proceeding with the release.

docs/extra.css

@@ -5,10 +5,6 @@ img {
     margin-right: auto;
 }
 
-.md-content img {
-    background-color: rgba(255, 255, 255, 0.64);
-}
-
 /* Tables */
 table {
     margin-bottom: 24px;

mkdocs.yml

@@ -1,3 +1,4 @@
+# Note: NetBox has migrated from MkDocs to Zensical
 site_name: NetBox Documentation
 site_dir: netbox/project-static/docs
 site_url: https://docs.netbox.dev/

netbox/project-static/docs/.info

@@ -1 +0,0 @@
-Build local for local documentation

requirements.txt

@@ -23,7 +23,6 @@ gunicorn==25.1.0
 Jinja2==3.1.6
 jsonschema==4.26.0
 Markdown==3.10.2
-mkdocs==1.6.1
 mkdocs-material==9.7.5
 mkdocstrings==1.0.3
 mkdocstrings-python==2.0.3
@@ -42,3 +41,4 @@ strawberry-graphql-django==0.82.0
 svgwrite==1.4.3
 tablib==3.9.0
 tzdata==2025.3
+zensical==0.0.28

upgrade.sh

@@ -105,7 +105,7 @@ echo "Checking for missing cable paths ($COMMAND)..."
 eval $COMMAND || exit 1
 
 # Build the local documentation
-COMMAND="mkdocs build"
+COMMAND="zensical build"
 echo "Building documentation ($COMMAND)..."
 eval $COMMAND || exit 1