♻️ Migrate docs to Zensical (#1913)

Author: tiangolo

data/members.yml

@@ -1,3 +1,5 @@
 members:
 - login: tiangolo
+- login: YuriiMotov
+- login: svlandeg
 - login: alejsdev

docs/contributing.md

@@ -100,10 +100,10 @@ Go into the docs directory at `docs/`:
 $ cd docs/
 ```
 
-Then run `mkdocs` in that directory:
+Then run `zensical` in that directory:
 
 ```console
-$ mkdocs serve --dev-addr 8008
+$ zensical serve --dev-addr 8008
 ```
 
 ///
@@ -129,7 +129,7 @@ Completion will take effect once you restart the terminal.
 
 ### Docs Structure
 
-The documentation uses <a href="https://www.mkdocs.org/" class="external-link" target="_blank">MkDocs</a>.
+The documentation uses <a href="https://zensical.org" class="external-link" target="_blank">Zensical</a>.
 
 And there are extra tools/scripts in place in `./scripts/docs.py`.
 

docs/index.md

@@ -1,3 +1,10 @@
+---
+include_yaml:
+    sponsors: data/sponsors.yml
+---
+
+#
+
 <style>
 .md-content .md-typeset h1 { display: none; }
 </style>

docs/management.md

@@ -1,3 +1,8 @@
+---
+include_yaml:
+    - data/members.yml
+---
+
 # Repository Management
 
 Here's a short description of how the SQLModel repository is managed and maintained.
@@ -29,7 +34,7 @@ Joining the team is by invitation only, and I could update or remove permissions
 This is the current list of team members. 😎
 
 <div class="user-list user-list-center">
-{% for user in members["members"] %}
+{% for user in members %}
 
 <div class="user"><a href="https://github.com/{{ user.login }}" target="_blank"><div class="avatar-wrapper"><img src="https://github.com/{{ user.login }}.png"/></div><div class="title">@{{ user.login }}</div></a></div>
 {% endfor %}

mkdocs.yml

@@ -3,6 +3,7 @@ site_name: SQLModel
 site_description: SQLModel, SQL databases in Python, designed for simplicity, compatibility, and robustness.
 site_url: https://sqlmodel.tiangolo.com/
 theme:
+  variant: classic
   name: material
   custom_dir: docs/overrides
   palette:
@@ -48,34 +49,24 @@ theme:
   - 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/sqlmodel
 repo_url: https://github.com/fastapi/sqlmodel
-plugins:
-  # Material for MkDocs
-  search:
-  social:
-  typeset:
-  # Other plugins
-  macros:
-    include_yaml:
-    - sponsors: data/sponsors.yml
-    - members: data/members.yml
 
 nav:
   - SQLModel: index.md
   - features.md
-  - Learn:
+  - "":
     - learn/index.md
     - databases.md
     - db-to-code.md
     - environment-variables.md
     - virtual-environments.md
     - install.md
-    - Tutorial - User Guide:
+    - "":
       - tutorial/index.md
       - tutorial/create-db-and-table-with-db-browser.md
       - tutorial/create-db-and-table.md
@@ -88,14 +79,14 @@ nav:
       - tutorial/limit-and-offset.md
       - tutorial/update.md
       - tutorial/delete.md
-      - Connect Tables - JOIN:
+      - "":
         - tutorial/connect/index.md
         - tutorial/connect/create-connected-tables.md
         - tutorial/connect/create-connected-rows.md
         - tutorial/connect/read-connected-data.md
         - tutorial/connect/update-data-connections.md
         - tutorial/connect/remove-data-connections.md
-      - Relationship Attributes:
+      - "":
         - tutorial/relationship-attributes/index.md
         - tutorial/relationship-attributes/define-relationships-attributes.md
         - tutorial/relationship-attributes/create-and-update-relationships.md
@@ -104,14 +95,14 @@ nav:
         - tutorial/relationship-attributes/back-populates.md
         - tutorial/relationship-attributes/cascade-delete-relationships.md
         - tutorial/relationship-attributes/type-annotation-strings.md
-      - Many to Many:
+      - "":
         - tutorial/many-to-many/index.md
         - tutorial/many-to-many/create-models-with-link.md
         - tutorial/many-to-many/create-data.md
         - tutorial/many-to-many/update-remove-relationships.md
         - tutorial/many-to-many/link-with-extra-fields.md
       - tutorial/code-structure.md
-      - FastAPI and Pydantic:
+      - "":
         - tutorial/fastapi/index.md
         - tutorial/fastapi/simple-hero-api.md
         - tutorial/fastapi/response-model.md
@@ -125,16 +116,16 @@ nav:
         - tutorial/fastapi/teams.md
         - tutorial/fastapi/relationships.md
         - tutorial/fastapi/tests.md
-    - Advanced User Guide:
+    - "":
       - advanced/index.md
       - advanced/decimal.md
       - advanced/uuid.md
-  - Resources:
+  - "":
     - resources/index.md
     - help.md
     - contributing.md
     - management-tasks.md
-  - About:
+  - "":
     - about/index.md
     - alternatives.md
     - management.md
@@ -146,6 +137,7 @@ markdown_extensions:
     targets:
       include:
         - "*"
+  zensical.extensions.macros:
   # Python Markdown
   abbr:
   attr_list:
@@ -194,18 +186,14 @@ markdown_extensions:
 
 extra:
   social:
-  - icon: fontawesome/brands/github-alt
-    link: https://github.com/fastapi/sqlmodel
-  - icon: fontawesome/brands/twitter
-    link: https://twitter.com/tiangolo
-  - icon: fontawesome/brands/linkedin
-    link: https://www.linkedin.com/in/tiangolo
-  - icon: fontawesome/brands/dev
-    link: https://dev.to/tiangolo
-  - icon: fontawesome/brands/medium
-    link: https://medium.com/@tiangolo
-  - icon: fontawesome/solid/globe
-    link: https://tiangolo.com
+    - icon: octicons/mark-github-24
+      link: https://github.com/fastapi/sqlmodel
+    - icon: fontawesome/brands/x-twitter
+      link: https://x.com/tiangolo
+    - icon: fontawesome/brands/bluesky
+      link: https://bsky.app/profile/tiangolo.com
+    - icon: fontawesome/brands/linkedin
+      link: https://www.linkedin.com/in/tiangolo
 
 extra_css:
   - css/termynal.css
@@ -215,5 +203,5 @@ extra_javascript:
   - js/termynal.js
   - js/custom.js
 
-hooks:
-  - scripts/mkdocs_hooks.py
+validation:
+  unresolved_references: false

pyproject.toml

@@ -61,13 +61,11 @@ docs = [
     "griffe-warnings-deprecated >=1.1.0",
     "markdown-include-variants >=0.0.8",
     "mdx-include >=1.4.1",
-    "mkdocs-macros-plugin >=1.5.0",
-    "mkdocs-material >=9.7.5",
-    "mkdocs-redirects >=1.2.1",
     "mkdocstrings[python] >=1.0.3",
     "pillow >=12.1.1",
     "pyyaml >=5.3.1",
     "typer >=0.24.1",
+    "zensical>=0.0.42",
 ]
 github-actions = [
     "httpx >=0.28.1",

scripts/docs.py

@@ -6,8 +6,8 @@
 from http.server import HTTPServer, SimpleHTTPRequestHandler
 from pathlib import Path
 
-import mkdocs.utils
 import typer
+import yaml
 from jinja2 import Template
 from ruff.__main__ import find_ruff_bin
 
@@ -45,7 +45,7 @@ def generate_readme_content() -> str:
     match_start = re.search(r"<!-- sponsors -->", content)
     match_end = re.search(r"<!-- /sponsors -->", content)
     sponsors_data_path = en_docs_path / "data" / "sponsors.yml"
-    sponsors = mkdocs.utils.yaml_load(sponsors_data_path.read_text(encoding="utf-8"))
+    sponsors = yaml.safe_load(sponsors_data_path.read_text(encoding="utf-8"))
     if not (match_start and match_end):
         raise RuntimeError("Couldn't auto-generate sponsors section")
     if not match_pre:
@@ -108,7 +108,7 @@ def live(dirty: bool = False) -> None:
     en.
     """
     # Enable line numbers during local development to make it easier to highlight
-    args = ["mkdocs", "serve", "--dev-addr", "127.0.0.1:8008"]
+    args = ["zensical", "serve", "--dev-addr", "127.0.0.1:8008"]
     if dirty:
         args.append("--dirty")
     subprocess.run(args, env={**os.environ, "LINENUMS": "true"}, check=True)
@@ -120,7 +120,7 @@ def build() -> None:
     Build the docs.
     """
     print("Building docs")
-    subprocess.run(["mkdocs", "build"], check=True)
+    subprocess.run(["zensical", "build"], check=True)
     typer.secho("Successfully built docs", color=typer.colors.GREEN)
 
 
@@ -129,7 +129,7 @@ def serve() -> None:
     """
     A quick server to preview a built site.
 
-    For development, prefer the command live (or just mkdocs serve).
+    For development, prefer the command live (or just zensical serve).
 
     This is here only to preview the documentation site.