zensical 0.0.3__cp310-abi3-musllinux_1_2_i686.whl → 0.0.9__cp310-abi3-musllinux_1_2_i686.whl

zensical/__init__.py

@@ -1,7 +1,7 @@
-# Copyright (c) Zensical LLC <https://zensical.org>
+# Copyright (c) 2025 Zensical and contributors
 
 # SPDX-License-Identifier: MIT
-# Third-party contributions licensed under CLA
+# Third-party contributions licensed under DCO
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to

zensical/__main__.py

@@ -0,0 +1,28 @@
+# Copyright (c) 2025 Zensical and contributors
+
+# SPDX-License-Identifier: MIT
+# Third-party contributions licensed under DCO
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+# Allow running as a script, with `python -m zensical`.
+from zensical.main import cli
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()

zensical/bootstrap/.github/workflows/docs.yml

@@ -1,21 +1,27 @@
-name: docs
+name: Documentation
 on:
   push:
     branches:
       - master
       - 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@v5
       - uses: actions/setup-python@v5
         with:
           python-version: 3.x
       - run: pip install zensical
-      - run: zensical build
+      - run: zensical build --clean
       - uses: actions/upload-pages-artifact@v4
         with:
           path: site

zensical/bootstrap/zensical.toml

@@ -49,6 +49,24 @@ Copyright © 2025 The authors
 #   { "Markdown in 5min" = "markdown.md" },
 # ]
 
+# With the "extra_css" option you can add your own CSS styling to customize
+# your Zensical project according to your needs. You can add any number of
+# CSS files.
+#
+# The path provided should be relative to the "docs_dir".
+#
+# Read more: https://zensical.org/docs/customization/#additional-css
+#
+#extra_css = ["assets/stylesheets/extra.css"]
+
+# With the `extra_javascript` option you can add your own JavaScript to your
+# project to customize the behavior according to your needs.
+#
+# The path provided should be relative to the "docs_dir".
+#
+# Read more: https://zensical.org/docs/customization/#additional-javascript
+#extra_javascript = ["assets/javascript/extra.js"]
+
 # ----------------------------------------------------------------------------
 # Section for configuring theme options
 # ----------------------------------------------------------------------------
@@ -176,7 +194,7 @@ features = [
     # In order to provide a better user experience on slow connections when
     # using instant navigation, a progress indicator can be enabled.
     # https://zensical.org/docs/setup/navigation/#progress-indicator
-    #"navigation.instant.progress"
+    #"navigation.instant.progress",
 
     # When navigation paths are activated, a breadcrumb navigation is rendered
     # above the title of each page
@@ -222,32 +240,14 @@ features = [
     # When anchor following for the table of contents is enabled, the sidebar
     # is automatically scrolled so that the active anchor is always visible.
     # https://zensical.org/docs/setup/navigation/#anchor-following
-    # "toc.follow"
+    # "toc.follow",
 
     # When navigation integration for the table of contents is enabled, it is
     # always rendered as part of the navigation sidebar on the left.
     # https://zensical.org/docs/setup/navigation/#navigation-integration
-    #"toc.integrate"
+    #"toc.integrate",
 ]
 
-# With the "extra_css" option you can add your own CSS styling to customize
-# your Zensical project according to your needs. You can add any number of
-# CSS files.
-#
-# The path provided should be relative to the "docs_dir".
-#
-# Read more: https://zensical.org/docs/customization/#additional-css
-#
-#extra_css = ["assets/stylesheets/extra.css"]
-
-# With the `extra_javascript` option you can add your own JavaScript to your
-# project to customize the behavior according to your needs.
-#
-# The path provided should be relative to the "docs_dir".
-#
-# Read more: https://zensical.org/docs/customization/#additional-javascript
-#extra_javascript = ["assets/javascript/extra.js"]
-
 # ----------------------------------------------------------------------------
 # In the "palette" subsection you can configure options for the color scheme.
 # You can configure different color # schemes, e.g., to turn on dark mode,

zensical/config.py

@@ -1,7 +1,7 @@
-# Copyright (c) Zensical LLC <https://zensical.org>
+# Copyright (c) 2025 Zensical and contributors
 
 # SPDX-License-Identifier: MIT
-# Third-party contributions licensed under CLA
+# Third-party contributions licensed under DCO
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to
@@ -23,14 +23,19 @@
 
 from __future__ import annotations
 
+import hashlib
 import importlib
 import os
-import tomllib
+import pickle
 import yaml
 
+try:
+    import tomllib
+except ModuleNotFoundError:
+    import tomli as tomllib  # type: ignore
+
 from click import ClickException
 from deepmerge import always_merger
-from functools import partial
 from typing import Any, IO
 from yaml import BaseLoader, Loader, YAMLError
 from yaml.constructor import ConstructorError
@@ -73,7 +78,9 @@ def parse_config(path: str) -> dict:
     """
     Parse configuration file.
     """
-    if path.endswith("zensical.toml"):
+    # Decide by extension; no need to convert to Path
+    _, ext = os.path.splitext(path)
+    if ext.lower() == ".toml":
         return parse_zensical_config(path)
     else:
         return parse_mkdocs_config(path)
@@ -107,6 +114,13 @@ def parse_mkdocs_config(path: str) -> dict:
     return _CONFIG
 
 
+def get_config():
+    """
+    Return configuration.
+    """
+    return _CONFIG
+
+
 def get_theme_dir() -> str:
     """
     Return the theme directory.
@@ -131,12 +145,12 @@ def _apply_defaults(config: dict, path: str) -> dict:
         raise ConfigurationError("Missing required setting: site_name")
 
     # Set site directory
-    config.setdefault("site_dir", "site")
+    set_default(config, "site_dir", "site", str)
     if ".." in config.get("site_dir"):
         raise ConfigurationError("site_dir must not contain '..'")
 
     # Set docs directory
-    config.setdefault("docs_dir", "docs")
+    set_default(config, "docs_dir", "docs", str)
     if ".." in config.get("docs_dir"):
         raise ConfigurationError("docs_dir must not contain '..'")
 
@@ -157,16 +171,17 @@ def _apply_defaults(config: dict, path: str) -> dict:
     # Set defaults for repository name settings
     repo_url = config.get("repo_url")
     if repo_url and not config.get("repo_name"):
+        docs_dir = config.get("docs_dir")
         host = urlparse(repo_url).hostname or ""
         if host == "github.com":
-            config["repo_name"] = "GitHub"
-            config["edit_uri"] = "edit/master/docs"
+            set_default(config, "repo_name", "GitHub", str)
+            set_default(config, "edit_uri", f"edit/master/{docs_dir}", str)
         elif host == "gitlab.com":
-            config["repo_name"] = "GitLab"
-            config["edit_uri"] = "edit/master/docs"
+            set_default(config, "repo_name", "GitLab", str)
+            set_default(config, "edit_uri", f"edit/master/{docs_dir}", str)
         elif host == "bitbucket.org":
-            config["repo_name"] = "Bitbucket"
-            config["edit_uri"] = "src/default/docs"
+            set_default(config, "repo_name", "Bitbucket", str)
+            set_default(config, "edit_uri", f"src/default/{docs_dir}", str)
         elif host:
             config["repo_name"] = host.split(".")[0].title()
 
@@ -176,7 +191,7 @@ def _apply_defaults(config: dict, path: str) -> dict:
         config["edit_uri"] = edit_uri.rstrip("/")
 
     # Set defaults for theme font settings
-    theme = config.setdefault("theme", {})
+    theme = set_default(config, "theme", {}, dict)
     if isinstance(theme, str):
         theme = {"name": theme}
         config["theme"] = theme
@@ -212,7 +227,7 @@ def _apply_defaults(config: dict, path: str) -> dict:
         set_default(theme["font"], "code", font["code"], str)
 
     # Set defaults for theme icons
-    icon = theme.setdefault("icon", {})
+    icon = set_default(theme, "icon", {}, dict)
     set_default(icon, "repo", None, str)
     set_default(icon, "annotation", None, str)
     set_default(icon, "tag", {}, dict)
@@ -242,7 +257,7 @@ def _apply_defaults(config: dict, path: str) -> dict:
         set_default(icon, "next", None, str)
 
     # Set defaults for theme admonition icons
-    admonition = icon.setdefault("admonition", {})
+    admonition = set_default(icon, "admonition", {}, dict)
     set_default(admonition, "note", None, str)
     set_default(admonition, "abstract", None, str)
     set_default(admonition, "info", None, str)
@@ -277,7 +292,7 @@ def _apply_defaults(config: dict, path: str) -> dict:
             set_default(toggle, "name", None, str)
 
     # Set defaults for extra settings
-    extra = config.setdefault("extra", {})
+    extra = set_default(config, "extra", {}, dict)
     set_default(extra, "homepage", None, str)
     set_default(extra, "scope", None, str)
     set_default(extra, "annotate", {}, dict)
@@ -374,7 +389,7 @@ def _apply_defaults(config: dict, path: str) -> dict:
                 "md_in_html": {},
                 "toc": {"permalink": True},
                 "pymdownx.arithmatex": {"generic": True},
-                "pymdownx.betterem": {"smart_enable": "all"},
+                "pymdownx.betterem": {},
                 "pymdownx.caret": {},
                 "pymdownx.details": {},
                 "pymdownx.emoji": {
@@ -416,18 +431,28 @@ def _apply_defaults(config: dict, path: str) -> dict:
     if isinstance(emoji.get("emoji_index"), str):
         emoji["emoji_index"] = _resolve(emoji.get("emoji_index"))
 
-    # Tabbed extension configuration - we need to resolve the slugification
-    # function.
+    # Tabbed extension configuration - resolve slugification function
     tabbed = config["mdx_configs"].get("pymdownx.tabbed", {})
     if isinstance(tabbed.get("slugify"), dict):
         object = tabbed["slugify"].get("object", "pymdownx.slugs.slugify")
-        tabbed["slugify"] = partial(
-            _resolve(object), tabbed["slugify"].get("kwds")
-        )
+        tabbed["slugify"] = _resolve(object)(**tabbed["slugify"].get("kwds"))
+
+    # Table of contents extension configuration - resolve slugification function
+    toc = config["mdx_configs"]["toc"]
+    if isinstance(toc.get("slugify"), dict):
+        object = toc["slugify"].get("object", "pymdownx.slugs.slugify")
+        toc["slugify"] = _resolve(object)(**toc["slugify"].get("kwds"))
+
+    # Superfences extension configuration - resolve format function
+    superfences = config["mdx_configs"].get("pymdownx.superfences", {})
+    for fence in superfences.get("custom_fences", []):
+        if isinstance(fence.get("format"), str):
+            fence["format"] = _resolve(fence.get("format"))
 
     # Ensure the table of contents title is initialized, as it's used inside
     # the template, and the table of contents extension is always defined
     config["mdx_configs"]["toc"].setdefault("title", None)
+    config["mdx_configs_hash"] = _hash(mdx_configs)
 
     # Convert plugins configuration
     config["plugins"] = _convert_plugins(config.get("plugins", []), config)
@@ -436,10 +461,13 @@ def _apply_defaults(config: dict, path: str) -> dict:
 
 def set_default(
     entry: dict, key: str, default: Any, data_type: type = None
-) -> None:
+) -> any:
     """
     Set a key to a default value if it isn't set, and optionally cast it to the specified data type.
     """
+    if key in entry and entry[key] is None:
+        del entry[key]
+
     # Set the default value if the key is not present
     entry.setdefault(key, default)
 
@@ -450,6 +478,17 @@ def set_default(
         except (ValueError, TypeError) as e:
             raise ValueError(f"Failed to cast key '{key}' to {data_type}: {e}")
 
+    # Return the resulting value
+    return entry[key]
+
+
+def _hash(data: any) -> int:
+    """
+    Compute a hash for the given data.
+    """
+    hash = hashlib.sha1(pickle.dumps(data))
+    return int(hash.hexdigest(), 16) % (2**64)
+
 
 def _convert_extra(data: dict | list) -> dict | list:
     """
@@ -594,7 +633,13 @@ def _convert_markdown_extensions(value: any):
     if "pymdownx" in value:
         pymdownx = value.pop("pymdownx")
         for ext, config in pymdownx.items():
-            value[f"pymdownx.{ext}"] = config
+            # Special case for blocks extension, which has another level of
+            # nesting. This is the only extension that requires this.
+            if ext == "blocks":
+                for block, config in config.items():
+                    value[f"pymdownx.{ext}.{block}"] = config
+            else:
+                value[f"pymdownx.{ext}"] = config
 
     # Extensions can be defined as a dict
     if isinstance(value, dict):
@@ -640,13 +685,15 @@ def _convert_plugins(value: any, config: dict) -> list:
                 plugins[item] = {}
 
     # Define defaults for search plugin
-    search = plugins.setdefault("search", {})
-    search.setdefault("enabled", True)
-    search.setdefault("separator", '[\\s\\-_,:!=\\[\\]()\\\\"`/]+|\\.(?!\\d)')
+    search = set_default(plugins, "search", {}, dict)
+    set_default(search, "enabled", True, bool)
+    set_default(
+        search, "separator", '[\\s\\-_,:!=\\[\\]()\\\\"`/]+|\\.(?!\\d)', str
+    )
 
     # Define defaults for offline plugin
-    offline = plugins.setdefault("offline", {"enabled": False})
-    offline.setdefault("enabled", True)
+    offline = set_default(plugins, "offline", {"enabled": False}, dict)
+    set_default(offline, "enabled", True, bool)
 
     # Ensure correct resolution of links when viewing the site from the
     # file system by disabling directory URLs
@@ -658,18 +705,20 @@ def _convert_plugins(value: any, config: dict) -> list:
             "iframe-worker" in url for url in config["extra"]["polyfills"]
         ):
             script = "https://unpkg.com/iframe-worker/shim"
-            config["extra"]["polyfills"].append(script)
-
-    # Ensure extra polyfills/shims use structured format
-    config["extra"]["polyfills"] = _convert_extra_javascript(
-        config["extra"]["polyfills"]
-    )
+            config["extra"]["polyfills"].append(
+                {
+                    "path": script,
+                    "type": "text/javascript",
+                    "async": False,
+                    "defer": False,
+                }
+            )
 
     # Now, add another level of indirection, by moving all plugin configuration
     # into a `config` property, making it compatible with Material for MkDocs.
-    for name, config in plugins.items():
-        if not isinstance(config, dict) or "config" not in config:
-            plugins[name] = {"config": config}
+    for name, data in plugins.items():
+        if not isinstance(data, dict) or "config" not in data:
+            plugins[name] = {"config": data}
 
     # Return plugins
     return plugins

zensical/extensions/__init__.py

@@ -1,7 +1,7 @@
-# Copyright (c) Zensical LLC <https://zensical.org>
+# Copyright (c) 2025 Zensical and contributors
 
 # SPDX-License-Identifier: MIT
-# Third-party contributions licensed under CLA
+# Third-party contributions licensed under DCO
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to

zensical/extensions/emoji.py

@@ -1,7 +1,7 @@
-# Copyright (c) Zensical LLC <https://zensical.org>
+# Copyright (c) 2025 Zensical and contributors
 
 # SPDX-License-Identifier: MIT
-# Third-party contributions licensed under CLA
+# Third-party contributions licensed under DCO
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to

zensical/extensions/links.py

@@ -1,7 +1,7 @@
-# Copyright (c) Zensical LLC <https://zensical.org>
+# Copyright (c) 2025 Zensical and contributors
 
 # SPDX-License-Identifier: MIT
-# Third-party contributions licensed under CLA
+# Third-party contributions licensed under DCO
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to
@@ -26,6 +26,7 @@ from __future__ import annotations
 from markdown import Extension, Markdown
 from markdown.treeprocessors import Treeprocessor
 from markdown.util import AMP_SUBSTITUTE
+from pathlib import PurePosixPath
 from xml.etree.ElementTree import Element
 from urllib.parse import urlparse
 
@@ -52,7 +53,7 @@ class LinksProcessor(Treeprocessor):
     def run(self, root: Element):
         # Now, we determine whether the current page is an index page, as we
         # must apply slightly different handling in case of directory URLs
-        current_is_index = self.path.endswith(("index.md", "README.md"))
+        current_is_index = get_name(self.path) in ("index.md", "README.md")
         for el in root.iter():
             # In case the element has a `href` or `src` attribute, we parse it
             # as an URL, so we can analyze and alter its path
@@ -81,10 +82,9 @@ class LinksProcessor(Treeprocessor):
             if path.endswith(".md"):
                 path = path.removesuffix(".md") + ".html"
                 if self.use_directory_urls:
-                    if path.endswith("index.html"):
-                        path = path[: -len("index.html")]
-                    elif path.endswith("README.html"):
-                        path = path[: -len("README.html")]
+                    name = get_name(path)
+                    if name in ("index.html", "README.html"):
+                        path = path[: -len(name)]
                     elif path.endswith(".html"):
                         path = path[: -len(".html")] + "/"
 
@@ -124,3 +124,16 @@ class LinksExtension(Extension):
         # before they are resolved to URLs.
         processor = LinksProcessor(md, self.path, self.use_directory_urls)
         md.treeprocessors.register(processor, "relpath", 0)
+
+
+# -----------------------------------------------------------------------------
+# Functions
+# -----------------------------------------------------------------------------
+
+
+def get_name(path: str) -> str:
+    """
+    Get the name of a file from a given path.
+    """
+    path = PurePosixPath(path)
+    return path.name

zensical/extensions/preview.py

@@ -1,7 +1,7 @@
-# Copyright (c) Zensical LLC <https://zensical.org>
+# Copyright (c) 2025 Zensical and contributors
 
 # SPDX-License-Identifier: MIT
-# Third-party contributions licensed under CLA
+# Third-party contributions licensed under DCO
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to

zensical/extensions/search.py

@@ -1,7 +1,7 @@
-# Copyright (c) Zensical LLC <https://zensical.org>
+# Copyright (c) 2025 Zensical and contributors
 
 # SPDX-License-Identifier: MIT
-# Third-party contributions licensed under CLA
+# Third-party contributions licensed under DCO
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to

zensical/extensions/utilities/__init__.py

@@ -1,7 +1,7 @@
-# Copyright (c) Zensical LLC <https://zensical.org>
+# Copyright (c) 2025 Zensical and contributors
 
 # SPDX-License-Identifier: MIT
-# Third-party contributions licensed under CLA
+# Third-party contributions licensed under DCO
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to

zensical/extensions/utilities/filter.py

@@ -1,7 +1,7 @@
-# Copyright (c) Zensical LLC <https://zensical.org>
+# Copyright (c) 2025 Zensical and contributors
 
 # SPDX-License-Identifier: MIT
-# Third-party contributions licensed under CLA
+# Third-party contributions licensed under DCO
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to

zensical/main.py

@@ -1,7 +1,7 @@
-# Copyright (c) Zensical LLC <https://zensical.org>
+# Copyright (c) 2025 Zensical and contributors
 
 # SPDX-License-Identifier: MIT
-# Third-party contributions licensed under CLA
+# Third-party contributions licensed under DCO
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to
@@ -26,11 +26,11 @@ from __future__ import annotations
 import click
 import os
 import shutil
-import webbrowser
 
 from click import ClickException
 from zensical import build, serve, version
 
+
 # ----------------------------------------------------------------------------
 # Commands
 # ----------------------------------------------------------------------------
@@ -122,17 +122,12 @@ def execute_serve(config_file: str | None, **kwargs):
                 break
         else:
             raise ClickException("No config file found in the current folder.")
-
-    # Obtain development server address and open in browser, if desired
-    dev_addr = kwargs.get("dev_addr") or "localhost:8000"
-    if kwargs.get("open", False):
-        webbrowser.open(f"http://{dev_addr}")
     if kwargs.get("strict", False):
         print("Warning: Strict mode is currently unsupported.")
 
     # Build project in Rust runtime, calling back into Python when necessary,
     # e.g., to parse MkDocs configuration format or render Markdown
-    serve(os.path.abspath(config_file), dev_addr)
+    serve(os.path.abspath(config_file), kwargs)
 
 
 @cli.command(name="new")
@@ -156,6 +151,7 @@ def new_project(directory: str | None, **kwargs):
         directory = "."
     docs_dir = os.path.join(directory, "docs")
     config_file = os.path.join(directory, "zensical.toml")
+    github_dir = os.path.join(directory, ".github")
 
     if os.path.exists(directory):
         if not os.path.isdir(directory):
@@ -164,6 +160,8 @@ def new_project(directory: str | None, **kwargs):
             raise (ClickException(f"{config_file} already exists."))
         if os.path.exists(docs_dir):
             raise (ClickException(f"{docs_dir} already exists."))
+        if os.path.exists(github_dir):
+            raise (ClickException(f"{github_dir} already exists."))
     else:
         os.makedirs(directory)
 
@@ -173,6 +171,10 @@ def new_project(directory: str | None, **kwargs):
         os.path.join(package_dir, "bootstrap/docs"),
         os.path.join(directory, "docs"),
     )
+    shutil.copytree(
+        os.path.join(package_dir, "bootstrap/.github"),
+        os.path.join(directory, ".github"),
+    )
 
 
 # ----------------------------------------------------------------------------

zensical/markdown.py

@@ -1,7 +1,7 @@
-# Copyright (c) Zensical LLC <https://zensical.org>
+# Copyright (c) 2025 Zensical and contributors
 
 # SPDX-License-Identifier: MIT
-# Third-party contributions licensed under CLA
+# Third-party contributions licensed under DCO
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to
@@ -30,7 +30,7 @@ from datetime import date, datetime
 from markdown import Markdown
 from yaml import SafeLoader
 
-from .config import _CONFIG
+from .config import get_config
 from .extensions.links import LinksExtension
 from .extensions.search import SearchExtension
 
@@ -61,7 +61,7 @@ def render(content: str, path: str) -> dict:
     in order to support the specific syntax of Python Markdown. We're working
     on moving the entire rendering chain to Rust.
     """
-    config = _CONFIG
+    config = get_config()
 
     # Initialize Markdown parser
     md = Markdown(