From 29239ca58a1225de1312b2ddb86267378fc5c0f5 Mon Sep 17 00:00:00 2001 From: Jeremy Stretch Date: Wed, 25 Mar 2026 11:48:29 -0400 Subject: [PATCH] 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 | 2 +- .pre-commit-config.yaml | 6 +++--- .readthedocs.yaml | 12 ++++++------ base_requirements.txt | 8 ++++---- docs/_theme/partials/copyright.html | 18 ------------------ docs/development/getting-started.md | 2 +- docs/development/release-checklist.md | 2 +- docs/extra.css | 4 ---- mkdocs.yml | 1 + netbox/project-static/docs/.info | 1 - requirements.txt | 2 +- upgrade.sh | 2 +- 12 files changed, 19 insertions(+), 41 deletions(-) delete mode 100644 docs/_theme/partials/copyright.html delete mode 100644 netbox/project-static/docs/.info diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b5ddfc724..d8698e8f5 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 361dfe72f..79b680f6b 100644 --- a/.pre-commit-config.yaml +++ b/.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 diff --git a/.readthedocs.yaml b/.readthedocs.yaml index c69c51748..5e6dda025 100644 --- a/.readthedocs.yaml +++ b/.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/ diff --git a/base_requirements.txt b/base_requirements.txt index 187ff4ef0..5a58f4df5 100644 --- a/base_requirements.txt +++ b/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 diff --git a/docs/_theme/partials/copyright.html b/docs/_theme/partials/copyright.html deleted file mode 100644 index cfbfd5444..000000000 --- a/docs/_theme/partials/copyright.html +++ /dev/null @@ -1,18 +0,0 @@ -
- {% if config.copyright %} -
- {{ config.copyright }} -
- {% endif %} - {% if not config.extra.generator == false %} - Made with - - Material for MkDocs - - {% endif %} -
-{% if not config.extra.build_public %} -
- ℹ️ Documentation is being served locally -
-{% endif %} diff --git a/docs/development/getting-started.md b/docs/development/getting-started.md index 956226760..993229d95 100644 --- a/docs/development/getting-started.md +++ b/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 diff --git a/docs/development/release-checklist.md b/docs/development/release-checklist.md index eb4001891..0cf75a6b3 100644 --- a/docs/development/release-checklist.md +++ b/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. diff --git a/docs/extra.css b/docs/extra.css index 4b8cd87fe..e953fa14c 100644 --- a/docs/extra.css +++ b/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; diff --git a/mkdocs.yml b/mkdocs.yml index 7b7f5a2f1..3c78965b2 100644 --- a/mkdocs.yml +++ b/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/ diff --git a/netbox/project-static/docs/.info b/netbox/project-static/docs/.info deleted file mode 100644 index c0cdaa5e8..000000000 --- a/netbox/project-static/docs/.info +++ /dev/null @@ -1 +0,0 @@ -Build local for local documentation diff --git a/requirements.txt b/requirements.txt index 556c867bd..75a6c717c 100644 --- a/requirements.txt +++ b/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 diff --git a/upgrade.sh b/upgrade.sh index ac4788def..f6dbd23a6 100755 --- a/upgrade.sh +++ b/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