🔧 Upgrade Material for MkDocs and remove insiders

.github/workflows/build-docs.yml

@@ -32,12 +32,9 @@ jobs:
             - docs/**
             - docs_src/**
             - requirements-docs.txt
-            - requirements-docs-insiders.txt
             - pyproject.toml
             - mkdocs.yml
-            - mkdocs.insiders.yml
-            - mkdocs.maybe-insiders.yml
-            - mkdocs.no-insiders.yml
+            - mkdocs.env.yml
             - .github/workflows/build-docs.yml
             - .github/workflows/deploy-docs.yml
             - scripts/mkdocs_hooks.py
@@ -63,12 +60,6 @@ jobs:
             pyproject.toml
       - name: Install docs extras
         run: uv pip install -r requirements-docs.txt
-      # Install MkDocs Material Insiders here just to put it in the cache for the rest of the steps
-      - name: Install Material for MkDocs Insiders
-        if: ( github.event_name != 'pull_request' || github.secret_source == 'Actions' )
-        run: uv pip install -r requirements-docs-insiders.txt
-        env:
-          TOKEN: ${{ secrets.FASTAPI_MKDOCS_MATERIAL_INSIDERS }}
       - name: Verify Docs
         run: python ./scripts/docs.py verify-docs
       - name: Export Language Codes
@@ -105,11 +96,6 @@ jobs:
             pyproject.toml
       - name: Install docs extras
         run: uv pip install -r requirements-docs.txt
-      - name: Install Material for MkDocs Insiders
-        if: ( github.event_name != 'pull_request' || github.secret_source == 'Actions' )
-        run: uv pip install -r requirements-docs-insiders.txt
-        env:
-          TOKEN: ${{ secrets.FASTAPI_MKDOCS_MATERIAL_INSIDERS }}
       - name: Update Languages
         run: python ./scripts/docs.py update-languages
       - uses: actions/cache@v4

docs/en/mkdocs.maybe-insiders.yml → docs/en/mkdocs.env.yml

@@ -1,6 +1,5 @@
 # Define this here and not in the main mkdocs.yml file because that one is auto
 # updated and written, and the script would remove the env var
-INHERIT: !ENV [INSIDERS_FILE, '../en/mkdocs.no-insiders.yml']
 markdown_extensions:
   pymdownx.highlight:
     linenums: !ENV [LINENUMS, false]

docs/en/mkdocs.yml

@@ -1,4 +1,4 @@
-INHERIT: ../en/mkdocs.maybe-insiders.yml
+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/
@@ -52,6 +52,10 @@ theme:
 repo_name: fastapi/fastapi
 repo_url: https://github.com/fastapi/fastapi
 plugins:
+  social:
+    cards_layout_options:
+      logo: ../en/docs/img/icon-white.svg
+  typeset:
   search: null
   macros:
     include_yaml:
@@ -253,6 +257,10 @@ nav:
   - management.md
 - release-notes.md
 markdown_extensions:
+  material.extensions.preview:
+    targets:
+      include:
+        - "*"
   abbr: null
   attr_list: null
   footnotes: null

requirements-docs.txt

@@ -1,6 +1,6 @@
 -e .
 -r requirements-docs-tests.txt
-mkdocs-material==9.6.16
+mkdocs-material==9.7.0
 mdx-include >=1.4.1,<2.0.0
 mkdocs-redirects>=1.2.1,<1.3.0
 typer == 0.16.0
@@ -13,6 +13,7 @@ pillow==11.3.0
 cairosvg==2.8.2
 mkdocstrings[python]==0.30.1
 griffe-typingdoc==0.3.0
+griffe-warnings-deprecated==1.1.0
 # For griffe, it formats with black
 black==25.1.0
 mkdocs-macros-plugin==1.4.1

scripts/docs.py

@@ -4,9 +4,7 @@
 import re
 import shutil
 import subprocess
-from functools import lru_cache
 from http.server import HTTPServer, SimpleHTTPRequestHandler
-from importlib import metadata
 from multiprocessing import Pool
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Union
@@ -47,12 +45,6 @@
 header_with_permalink_pattern = re.compile(r"^(#{1,6}) (.+?)(\s*\{\s*#.*\s*\})\s*$")
 
 
-@lru_cache
-def is_mkdocs_insiders() -> bool:
-    version = metadata.version("mkdocs-material")
-    return "insiders" in version
-
-
 def get_en_config() -> Dict[str, Any]:
     return mkdocs.utils.yaml_load(en_config_path.read_text(encoding="utf-8"))
 
@@ -77,9 +69,7 @@ def complete_existing_lang(incomplete: str):
 
 @app.callback()
 def callback() -> None:
-    if is_mkdocs_insiders():
-        os.environ["INSIDERS_FILE"] = "../en/mkdocs.insiders.yml"
-    # For MacOS with insiders and Cairo
+    # For MacOS with Cairo
     os.environ["DYLD_FALLBACK_LIBRARY_PATH"] = "/opt/homebrew/lib"
 
 
@@ -115,10 +105,6 @@ def build_lang(
     """
     Build the docs for a language.
     """
-    insiders_env_file = os.environ.get("INSIDERS_FILE")
-    print(f"Insiders file {insiders_env_file}")
-    if is_mkdocs_insiders():
-        print("Using insiders")
     lang_path: Path = Path("docs") / lang
     if not lang_path.is_dir():
         typer.echo(f"The language translation doesn't seem to exist yet: {lang}")