🔧 Upgrade Material for MkDocs and remove insiders (#1650)

Author: tiangolo

.github/workflows/build-docs.yml

@@ -33,12 +33,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
             - data/**
@@ -68,11 +65,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.SQLMODEL_MKDOCS_MATERIAL_INSIDERS }}
       - uses: actions/cache@v4
         with:
           key: mkdocs-cards-${{ github.ref }}

mkdocs.maybe-insiders.yml renamed to mkdocs.env.yml

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

mkdocs.insiders.yml

@@ -1,4 +1,4 @@
-INHERIT: ./mkdocs.maybe-insiders.yml
+INHERIT: ./mkdocs.env.yml
 site_name: SQLModel
 site_description: SQLModel, SQL databases in Python, designed for simplicity, compatibility, and robustness.
 site_url: https://sqlmodel.tiangolo.com/
@@ -58,6 +58,7 @@ plugins:
   # Material for MkDocs
   search:
   social:
+  typeset:
   # Other plugins
   macros:
     include_yaml:
@@ -140,6 +141,11 @@ nav:
   - release-notes.md
 
 markdown_extensions:
+  # Material for MkDocs
+  material.extensions.preview:
+    targets:
+      include:
+        - "*"
   # Python Markdown
   abbr:
   attr_list:

mkdocs.no-insiders.yml

@@ -10,8 +10,9 @@ pyyaml >=5.3.1,<7.0.0
 pillow==11.3.0
 # For image processing by Material for MkDocs
 cairosvg==2.8.2
-# mkdocstrings[python]==0.25.1
+mkdocstrings[python]==0.30.1
 griffe-typingdoc==0.3.0
+griffe-warnings-deprecated==1.1.0
 # For griffe, it formats with black
 typer == 0.20.0
 mkdocs-macros-plugin==1.5.0

mkdocs.yml

@@ -2,9 +2,7 @@
 import os
 import re
 import subprocess
-from functools import lru_cache
 from http.server import HTTPServer, SimpleHTTPRequestHandler
-from importlib import metadata
 from pathlib import Path
 
 import mkdocs.utils
@@ -19,17 +17,9 @@
 app = typer.Typer()
 
 
-@lru_cache
-def is_mkdocs_insiders() -> bool:
-    version = metadata.version("mkdocs-material")
-    return "insiders" in version
-
-
 @app.callback()
 def callback() -> None:
-    if is_mkdocs_insiders():
-        os.environ["INSIDERS_FILE"] = "./mkdocs.insiders.yml"
-    # For MacOS with insiders and Cairo
+    # For MacOS with Cairo
     os.environ["DYLD_FALLBACK_LIBRARY_PATH"] = "/opt/homebrew/lib"
 
 
@@ -126,10 +116,6 @@ def build() -> None:
     """
     Build the docs.
     """
-    insiders_env_file = os.environ.get("INSIDERS_FILE")
-    print(f"Insiders file {insiders_env_file}")
-    if is_mkdocs_insiders():
-        print("Using insiders")
     print("Building docs")
     subprocess.run(["mkdocs", "build"], check=True)
     typer.secho("Successfully built docs", color=typer.colors.GREEN)