🔧 Migrate docs from MkDocs to Zensical (fastapi#15563)

Author: tiangolo

.github/workflows/build-docs.yml

@@ -34,14 +34,13 @@ jobs:
             - docs_src/**
             - pyproject.toml
             - uv.lock
-            - mkdocs.yml
-            - mkdocs.env.yml
             - .github/workflows/build-docs.yml
             - .github/workflows/deploy-docs.yml
-            - scripts/mkdocs_hooks.py
+            - scripts/docs.py
   langs:
     needs:
       - changes
+    if: ${{ needs.changes.outputs.docs == 'true' }}
     runs-on: ubuntu-latest
     outputs:
       langs: ${{ steps.show-langs.outputs.langs }}
@@ -103,26 +102,33 @@ jobs:
         run: uv run ./scripts/docs.py update-languages
       - uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
         with:
-          key: mkdocs-cards-${{ matrix.lang }}-${{ github.ref }}
-          path: docs/${{ matrix.lang }}/.cache
+          key: zensical-${{ matrix.lang }}-${{ github.ref }}
+          path: site_zensical_src/${{ matrix.lang }}/.cache
       - name: Build Docs
         run: | # zizmor: ignore[template-injection] - comes from trusted source
           uv run ./scripts/docs.py build-lang ${{ matrix.lang }}
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: docs-site-${{ matrix.lang }}
-          path: ./site/**
+          # English owns root static assets. Translated pages reference /img, /css,
+          # and /js, so omit duplicated language-local copies from artifacts.
+          path: |
+            ./site/**
+            !./site/${{ matrix.lang }}/img/**
+            !./site/${{ matrix.lang }}/css/**
+            !./site/${{ matrix.lang }}/js/**
           include-hidden-files: true
 
   # https://github.com/marketplace/actions/alls-green#why
   docs-all-green:  # This job does nothing and is only used for the branch protection
     if: always()
     needs:
+      - langs
       - build-docs
     runs-on: ubuntu-latest
     steps:
       - name: Decide whether the needed jobs succeeded or failed
         uses: re-actors/alls-green@05ac9388f0aebcb5727afa17fcccfecd6f8ec5fe # v1.2.2
         with:
           jobs: ${{ toJSON(needs) }}
-          allowed-skips: build-docs
+          allowed-skips: langs, build-docs

.gitignore

@@ -7,6 +7,7 @@ __pycache__
 htmlcov
 dist
 site
+site_zensical_src
 .coverage*
 coverage.xml
 .netlify

docs/de/docs/index.md

@@ -1,3 +1,8 @@
+---
+include_yaml:
+  sponsors: data/sponsors.yml
+---
+
 # FastAPI { #fastapi }
 
 <style>

docs/de/mkdocs.yml

@@ -100,10 +100,10 @@ Go into the language directory, for the main docs in English it's at `docs/en/`:
 $ cd docs/en/
 ```
 
-Then run `mkdocs` in that directory:
+Then run `zensical` in that directory:
 
 ```console
-$ mkdocs serve --dev-addr 127.0.0.1:8008
+$ zensical serve --dev-addr 127.0.0.1:8008
 ```
 
 ///
@@ -129,7 +129,7 @@ Completion will take effect once you restart the terminal.
 
 ### Docs Structure
 
-The documentation uses [MkDocs](https://www.mkdocs.org/).
+The documentation uses [Zensical](https://zensical.org).
 
 And there are extra tools/scripts in place to handle translations in `./scripts/docs.py`.
 

docs/en/docs/contributing.md

@@ -1,3 +1,8 @@
+---
+include_yaml:
+  topic_repos: data/topic_repos.yml
+---
+
 # External Links
 
 **FastAPI** has a great community constantly growing.

docs/en/docs/external-links.md

@@ -1,6 +1,16 @@
 ---
 hide:
   - navigation
+
+include_yaml:
+  github_sponsors: data/github_sponsors.yml
+  people: data/people.yml
+  contributors: data/contributors.yml
+  translation_reviewers: data/translation_reviewers.yml
+  skip_users: data/skip_users.yml
+  members: data/members.yml
+  sponsors_badge: data/sponsors_badge.yml
+  sponsors: data/sponsors.yml
 ---
 
 # FastAPI People

docs/en/docs/fastapi-people.md

@@ -1,3 +1,8 @@
+---
+include_yaml:
+  sponsors: data/sponsors.yml
+---
+
 # FastAPI { #fastapi }
 
 <style>

docs/en/docs/index.md

@@ -1,10 +1,10 @@
-INHERIT: ../en/mkdocs.env.yml
 site_name: FastAPI
 site_description: FastAPI framework, high performance, easy to learn, fast to code, ready for production
 site_url: https://fastapi.tiangolo.com/
 theme:
+  variant: classic
   name: material
-  custom_dir: ../en/overrides
+  custom_dir: overrides
   palette:
   - media: (prefers-color-scheme)
     toggle:
@@ -45,38 +45,13 @@ theme:
   - search.suggest
   - toc.follow
   icon:
-    repo: fontawesome/brands/github-alt
+    repo: octicons/mark-github-24
   logo: img/icon-white.svg
   favicon: img/favicon.png
   language: en
 repo_name: fastapi/fastapi
 repo_url: https://github.com/fastapi/fastapi
 plugins:
-  social:
-    cards_layout_options:
-      logo: ../en/docs/img/icon-white.svg
-  typeset: null
-  search: null
-  macros:
-    include_yaml:
-    - github_sponsors: ../en/data/github_sponsors.yml
-    - people: ../en/data/people.yml
-    - contributors: ../en/data/contributors.yml
-    - translators: ../en/data/translators.yml
-    - translation_reviewers: ../en/data/translation_reviewers.yml
-    - skip_users: ../en/data/skip_users.yml
-    - members: ../en/data/members.yml
-    - sponsors_badge: ../en/data/sponsors_badge.yml
-    - sponsors: ../en/data/sponsors.yml
-    - topic_repos: ../en/data/topic_repos.yml
-  redirects:
-    redirect_maps:
-      deployment/deta.md: deployment/cloud.md
-      advanced/graphql.md: how-to/graphql.md
-      advanced/custom-request-and-route.md: how-to/custom-request-and-route.md
-      advanced/conditional-openapi.md: how-to/conditional-openapi.md
-      advanced/extending-openapi.md: how-to/extending-openapi.md
-      advanced/testing-database.md: how-to/testing-database.md
   mkdocstrings:
     handlers:
       python:
@@ -102,13 +77,13 @@ plugins:
 nav:
 - FastAPI: index.md
 - features.md
-- Learn:
+- "":
   - learn/index.md
   - python-types.md
   - async.md
   - environment-variables.md
   - virtual-environments.md
-  - Tutorial - User Guide:
+  - "":
     - tutorial/index.md
     - tutorial/first-steps.md
     - tutorial/path-params.md
@@ -137,14 +112,14 @@ nav:
     - tutorial/path-operation-configuration.md
     - tutorial/encoder.md
     - tutorial/body-updates.md
-    - Dependencies:
+    - "":
       - tutorial/dependencies/index.md
       - tutorial/dependencies/classes-as-dependencies.md
       - tutorial/dependencies/sub-dependencies.md
       - tutorial/dependencies/dependencies-in-path-operation-decorators.md
       - tutorial/dependencies/global-dependencies.md
       - tutorial/dependencies/dependencies-with-yield.md
-    - Security:
+    - "":
       - tutorial/security/index.md
       - tutorial/security/first-steps.md
       - tutorial/security/get-current-user.md
@@ -161,7 +136,7 @@ nav:
     - tutorial/static-files.md
     - tutorial/testing.md
     - tutorial/debugging.md
-  - Advanced User Guide:
+  - "":
     - advanced/index.md
     - advanced/stream-data.md
     - advanced/path-operation-advanced-configuration.md
@@ -173,7 +148,7 @@ nav:
     - advanced/response-headers.md
     - advanced/response-change-status-code.md
     - advanced/advanced-dependencies.md
-    - Advanced Security:
+    - "":
       - advanced/security/index.md
       - advanced/security/oauth2-scopes.md
       - advanced/security/http-basic-auth.md
@@ -199,7 +174,7 @@ nav:
     - advanced/strict-content-type.md
   - fastapi-cli.md
   - editor-support.md
-  - Deployment:
+  - "":
     - deployment/index.md
     - deployment/versions.md
     - deployment/fastapicloud.md
@@ -209,7 +184,7 @@ nav:
     - deployment/cloud.md
     - deployment/server-workers.md
     - deployment/docker.md
-  - How To - Recipes:
+  - "":
     - how-to/index.md
     - how-to/general.md
     - how-to/migrate-from-pydantic-v1-to-pydantic-v2.md
@@ -222,7 +197,7 @@ nav:
     - how-to/configure-swagger-ui.md
     - how-to/testing-database.md
     - how-to/authentication-error-status-code.md
-- Reference (Code API):
+- "":
   - reference/index.md
   - reference/fastapi.md
   - reference/parameters.md
@@ -238,7 +213,7 @@ nav:
   - reference/response.md
   - reference/responses.md
   - reference/middleware.md
-  - OpenAPI:
+  - "":
     - reference/openapi/index.md
     - reference/openapi/docs.md
     - reference/openapi/models.md
@@ -248,26 +223,23 @@ nav:
   - reference/templating.md
   - reference/testclient.md
 - fastapi-people.md
-- Resources:
+- "":
   - resources/index.md
   - help-fastapi.md
   - contributing.md
   - project-generation.md
   - external-links.md
   - newsletter.md
   - management-tasks.md
-- About:
+- "":
   - about/index.md
   - alternatives.md
   - history-design-future.md
   - benchmarks.md
   - management.md
 - release-notes.md
 markdown_extensions:
-  material.extensions.preview:
-    targets:
-      include:
-      - '*'
+  zensical.extensions.macros: null
   abbr: null
   attr_list: null
   footnotes: null
@@ -312,16 +284,16 @@ markdown_extensions:
   markdown_include_variants: null
 extra:
   social:
-  - icon: fontawesome/brands/github-alt
+  - icon: octicons/mark-github-24
     link: https://github.com/fastapi/fastapi
   - icon: fontawesome/brands/discord
     link: https://discord.gg/VQjSZaeJmf
-  - icon: fontawesome/brands/twitter
+  - icon: fontawesome/brands/x-twitter
     link: https://x.com/fastapi
+  - icon: fontawesome/brands/bluesky
+    link: https://bsky.app/profile/fastapi.tiangolo.com
   - icon: fontawesome/brands/linkedin
     link: https://www.linkedin.com/company/fastapi
-  - icon: fontawesome/solid/globe
-    link: https://tiangolo.com
   alternate:
   - link: /
     name: en - English
@@ -354,5 +326,5 @@ extra_javascript:
 - js/termynal.js
 - js/custom.js
 - js/init_kapa_widget.js
-hooks:
-- ../../scripts/mkdocs_hooks.py
+validation:
+  unresolved_references: false