Migrate from mkdocs-material to zensical

.github/workflows/ci.yml

@@ -4,11 +4,17 @@ on:
     branches:
       - main
 permissions:
-  contents: write
+  contents: read
+  pages: write
+  id-token: write
 jobs:
   deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     steps:
+      - uses: actions/configure-pages@v5
       - uses: actions/checkout@v4
 
       - uses: actions/setup-python@v5
@@ -18,19 +24,12 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@v3
 
-      - name: Configure Git Credentials
-        # see https://api.github.com/users/github-actions%5Bbot%5D
-        run: |
-          git config user.name github-actions[bot]
-          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
-
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
-      - uses: actions/cache@v4
-        with:
-          key: mkdocs-material-${{ env.cache_id }}
-          path: .cache
-          restore-keys: |
-            mkdocs-material-
       - run: uv sync
       - run: uv pip install .
-      - run: uv run mkdocs gh-deploy --force
+      - run: uv run zensical build --clean --strict
+
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+      - uses: actions/deploy-pages@v4
+        id: deployment

.gitignore

@@ -1 +1,2 @@
 .idea
+site/

README.md

@@ -26,12 +26,12 @@ Assuming you've already cloned this repository:
 3. Start the project
 
     ```shell
-    uv run mkdocs serve
+    uv run zensical serve
     ```
 
 ### Writing
 
-See the [MkDocs documentation](https://www.mkdocs.org/user-guide/writing-your-docs/) for how to write documentation.
+See the [Zensical documentation](https://zensical.org/docs/) for how to write documentation.
 
 
 ### API docs

docs/changelog.md

@@ -79,7 +79,7 @@ hide:
 
 ## Mar 18, 2026
 * **NEW** Added support for **Meta Cloud API** as a new WhatsApp messaging provider, enabling direct integration with the WhatsApp Business Platform without requiring a third-party intermediary. Configure it using your WhatsApp Business Account ID, System User Access Token, App Secret, and Webhook Verify Token.
-* **NEW** Added a [**Set Session State Key**](concepts/tools/index.md#set-session-state-key) and [**Get Session State**](concepts/tools/index.md#get-session-state) built-in tools that allow LLM nodes to read and write data from the [session state](concepts/sessions.md) during a conversation.
+* **NEW** Added a [**Set Session State Key**](concepts/tools/index.md#set-session-state-key) and [**Get Session State**](concepts/tools/index.md#get-session-state-key) built-in tools that allow LLM nodes to read and write data from the [session state](concepts/sessions.md) during a conversation.
 * **NEW** Added [**Append to Session State**](concepts/tools/index.md#append-to-session-state) and [**Increment Session State Counter**](concepts/tools/index.md#increment-session-state-counter) built-in tools, mirroring the existing participant data tools for managing lists and counters in session state.
 
 ## Mar 17, 2026

docs/concepts/participant_data.md

@@ -103,7 +103,5 @@ data:
 }
 ```
 
-See [the API docs][api_docs]{target="_blank"}
+See [the API docs](https://openchatstudio.com/api/docs/#tag/Participants/operation/update_participant_data){target="_blank"}
 for more information on the API.
-
-[api_docs]: https://openchatstudio.com/api/docs/#tag/Participants/operation/update_participant_data

docs/how-to/add_a_knowledge_base.md

@@ -31,6 +31,5 @@ To add knowledge to your assistant, you must upload files to serve as the source
 
 [source_material_concept]: ../concepts/source_material.md
 [prompt_variables_concept]: ../concepts/prompt_variables.md
-[assistants]: https://platform.openai.com/docs/assistants/overview
 [file_search]: https://platform.openai.com/docs/assistants/tools/file-search
 [code_interpreter]: https://platform.openai.com/docs/assistants/tools/code-interpreter

docs/how-to/deploy_to_different_channels.md

@@ -195,7 +195,5 @@ If a pipeline-produced file cannot be sent as an attachment (for example, it exc
 [4]: https://www.twilio.com/docs/conversations/Facebook-messenger#setting-up-the-Facebook-messenger-channel
 [5]: https://core.Telegram.org/bots/features#:~:text=/setjoingroups%20%E2%80%93%20toggle%20whether%20your%20bot%20can%20be%20added%20to%20groups%20or%20not.%20All%20bots%20must%20be%20able%20to%20process%20direct%20messages%2C%20but%20if%20your%20bot%20was%20not%20designed%20to%20work%20in%20groups%2C%20you%20can%20disable%20this.
 [6]: ../tutorials/configure_providers.md
-[7]: https://openchatstudio.com/users/profile/
-[8]: https://openchatstudio.com/api/docs/
 [api]: ../tech-hub/api_access.md
 [meta]: ./whatsapp_meta_cloud_api.md

docs/how-to/workflow_cookbook.md

@@ -169,6 +169,4 @@ See documentation on [How to call external APIs](../tech-hub/external-api-calls/
 [prompt_vars]: ../concepts/prompt_variables.md
 [temp_state]: ../tech-hub/python_node.md#temporary-state
 [attachments]: ../tech-hub/python_node.md#attachments
-[code_node_supported_file_types]: ../tech-hub/python_node.md#supported-file-types
-[http_client]: ../tech-hub/external-api-calls/http_client.md
-[auth_providers]: ../concepts/team/authentication_providers.md
+[code_node_supported_file_types]: ../tech-hub/python_node.md#supported-file-types

mkdocs.yml

@@ -72,12 +72,11 @@ markdown_extensions:
 
 plugins:
 - search
+- macros
 - git-revision-date-localized
 - redirects:
     redirect_maps:
       'concepts/team/tracing_providers.md': 'concepts/tracing.md'
-- macros:
-    render_by_default: false
 - mkdocstrings:
     enabled: true
     default_handler: python

pyproject.toml

@@ -6,10 +6,9 @@ readme = "README.md"
 requires-python = ">=3.13"
 dependencies = [
     "mkdocs-git-revision-date-localized-plugin>=1.5.0",
-    "mkdocs-macros-plugin>=1.3.7",
-    "mkdocs-material",
+    "zensical>=0.0.40",
     "mkdocs-redirects>=1.2.0",
-    "mkdocstrings[python]",
+    "mkdocstrings[python]>=1.0.0",
     "requests>=2.32.3",
 ]
 

src/python_node/__init__.py

@@ -44,7 +44,7 @@ def get_temp_state_key(key_name: str) -> str | None:
     Returns the value of the temporary state key with the given name.
     If the key does not exist, it returns `None`.
 
-    See also: [Temporary State](./#temporary-state)
+    See also: [Temporary State](tech-hub/python_node.md#temporary-state)
     """
 
 
@@ -53,7 +53,7 @@ def set_temp_state_key(key_name: str, data: Any) -> None:
     Sets the value of the temporary state key with the given name to the provided data.
     This will override any existing data for the key.
 
-    See also: [Temporary State](./#temporary-state)
+    See also: [Temporary State](tech-hub/python_node.md#temporary-state)
     """
 
 
@@ -62,7 +62,7 @@ def get_session_state_key(key_name: str) -> str | None:
     Returns the value of the session state key with the given name.
     If the key does not exist, it returns `None`.
 
-    See also: [Session State](./#session-state)
+    See also: [Session State](tech-hub/python_node.md#session-state)
     """
 
 
@@ -71,7 +71,7 @@ def set_session_state_key(key_name: str, data: Any) -> None:
     Sets the value of the session state key with the given name to the provided data.
     This will override any existing data for the key.
 
-    See also: [Session State](./#session-state)
+    See also: [Session State](tech-hub/python_node.md#session-state)
     """
 
 
@@ -212,7 +212,7 @@ def main_explicit_mime(input, **kwargs):
             return "Failed to retrieve export."
         ```
 
-    See also: [HTTP Client - Downloading and Attaching Files](external-api-calls/http_client.md#downloading-and-attaching-files)
+    See also: [HTTP Client - Downloading and Attaching Files](tech-hub/external-api-calls/http_client.md#downloading-and-attaching-files)
     """
 
 def end_session() -> None: