webifier-extensions 1.0.1__tar.gz

webifier_extensions-1.0.1/.github/workflows/python-publish.yml

@@ -0,0 +1,49 @@
+name: Upload Python Package
+
+on:
+  push:
+    tags:
+      - "v*"
+  release:
+    types: [created]
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+
+      - name: Verify release tag
+        run: |
+          TAG="$(git describe --tags --exact-match)"
+          case "$TAG" in
+            v[0-9]*)
+              echo "Publishing $TAG"
+              ;;
+            *)
+              echo "Refusing to publish from non-release tag: $TAG"
+              exit 1
+              ;;
+          esac
+
+      - name: Build and publish
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: |
+          python -m build --sdist --wheel
+          python -m twine check dist/*
+          python -m twine upload dist/*

webifier_extensions-1.0.1/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.DS_Store
+**/.DS_Store
+dist/
+build/

webifier_extensions-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vahid Zehtab
+
+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 NONINFRINGEMENT. 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.

webifier_extensions-1.0.1/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: webifier-extensions
+Version: 1.0.1
+Summary: First-party extensions for Webifier static sites.
+Author-email: Vahid Zehtab <vahid98zee@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: beautifulsoup4
+Requires-Dist: markupsafe
+Requires-Dist: nbconvert<8,>=7
+Requires-Dist: nbformat
+Provides-Extra: dev
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Webifier Extensions
+
+First-party extensions for Webifier.
+
+This distribution is installed automatically when users install `webifier`:
+
+```shell
+pip install webifier
+```
+
+For local extension development, install this package in the same environment as
+the local Webifier core.
+
+Enable named instances in a site configuration:
+
+```yaml
+config:
+  webifier:
+    extensions:
+      site:
+        uses: webifier.standard
+      markdown:
+        uses: webifier.markdown
+      search:
+        uses: webifier.search
+```
+
+Extensions can register renderers, content renderers, templates, themes, assets,
+resolvers, format loaders, hooks, and config defaults. Hooks are page-aware, so a
+`head` hook can inspect the current page data or page-local config and inject
+JavaScript only on pages that need it.

webifier_extensions-1.0.1/README.md

@@ -0,0 +1,31 @@
+# Webifier Extensions
+
+First-party extensions for Webifier.
+
+This distribution is installed automatically when users install `webifier`:
+
+```shell
+pip install webifier
+```
+
+For local extension development, install this package in the same environment as
+the local Webifier core.
+
+Enable named instances in a site configuration:
+
+```yaml
+config:
+  webifier:
+    extensions:
+      site:
+        uses: webifier.standard
+      markdown:
+        uses: webifier.markdown
+      search:
+        uses: webifier.search
+```
+
+Extensions can register renderers, content renderers, templates, themes, assets,
+resolvers, format loaders, hooks, and config defaults. Hooks are page-aware, so a
+`head` hook can inspect the current page data or page-local config and inject
+JavaScript only on pages that need it.

webifier_extensions-1.0.1/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "webifier-extensions"
+version = "1.0.1"
+description = "First-party extensions for Webifier static sites."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Vahid Zehtab", email = "vahid98zee@gmail.com" },
+]
+dependencies = [
+    "beautifulsoup4",
+    "markupsafe",
+    "nbconvert>=7,<8",
+    "nbformat",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff",
+]
+
+[project.entry-points."webifier.extensions"]
+"webifier.standard" = "webifier_extensions.standard.extension:StandardExtension"
+"webifier.markdown" = "webifier_extensions.markdown.extension:MarkdownExtension"
+"webifier.notebook" = "webifier_extensions.notebook.extension:NotebookExtension"
+"webifier.search" = "webifier_extensions.search.extension:SearchExtension"
+"webifier.theme" = "webifier_extensions.theme.extension:ThemeExtension"
+"webifier.analytics.google" = "webifier_extensions.analytics.google.extension:GoogleAnalyticsExtension"
+"webifier.comments" = "webifier_extensions.comments.extension:CommentsExtension"
+"webifier.people" = "webifier_extensions.people.extension:PeopleExtension"
+"webifier.chapters" = "webifier_extensions.chapters.extension:ChaptersExtension"
+"webifier.resume" = "webifier_extensions.resume.extension:ResumeExtension"
+
+[tool.hatch.build.targets.wheel]
+packages = ["webifier_extensions"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["webifier_extensions"]

webifier_extensions-1.0.1/webifier_extensions/_resources.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+import importlib.util
+import os
+
+
+def package_path(package: str, *parts: str) -> str:
+    spec = importlib.util.find_spec(package)
+    if not spec or not spec.submodule_search_locations:
+        raise ValueError(f"Cannot locate package resources for {package!r}.")
+    return os.path.join(next(iter(spec.submodule_search_locations)), *parts)

webifier_extensions-1.0.1/webifier_extensions/analytics/google/extension.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from markupsafe import Markup
+from webifier.core.extensions import Extension, ExtensionContext
+
+
+class GoogleAnalyticsExtension(Extension):
+    id = "webifier.analytics.google"
+    config_key = "google_analytics"
+
+    def register(self, ctx: ExtensionContext) -> None:
+        super().register(ctx)
+        ctx.add_hook("head", self.render_head)
+
+    def render_head(self, builder, *, config=None, **_kwargs) -> str:
+        analytics = {}
+        if isinstance(config, dict):
+            analytics = config.get("google_analytics", {})
+        if analytics is False or (
+            isinstance(analytics, dict) and analytics.get("enabled") is False
+        ):
+            return ""
+        if not isinstance(analytics, dict):
+            analytics = {}
+        measurement_id = analytics.get("measurement_id") or analytics.get("id")
+        if not measurement_id:
+            return ""
+        return Markup(
+            "\n".join(
+                [
+                    "<!-- Global site tag (gtag.js) - Google Analytics -->",
+                    f'<script async src="https://www.googletagmanager.com/gtag/js?id={measurement_id}"></script>',
+                    "<script>",
+                    "  window.dataLayer = window.dataLayer || [];",
+                    "  function gtag(){dataLayer.push(arguments);}",
+                    "  gtag('js', new Date());",
+                    f"  gtag('config', '{measurement_id}');",
+                    "</script>",
+                ]
+            )
+        )

webifier_extensions-1.0.1/webifier_extensions/chapters/extension.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from webifier.core.extensions import Extension
+
+
+class ChaptersExtension(Extension):
+    id = "webifier.chapters"
+    dependencies = ("webifier.standard",)
+    renderers = {
+        "chapters": "webifier_extensions.chapters.renderer.ChaptersRenderer",
+    }

webifier_extensions-1.0.1/webifier_extensions/chapters/renderer.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from webifier.core.base import NodeContext, RendererModule
+
+
+class ChaptersRenderer(RendererModule):
+    """Render chapters as a Bootstrap accordion."""
+
+    template: ClassVar[str] = "macros/chapters.html"
+    META_KEYS: ClassVar[frozenset[str]] = frozenset(
+        {
+            "kind",
+            "template",
+            "label",
+            "background",
+            "style",
+            "content",
+        }
+    )
+
+    def process(self, data: dict[str, Any], ctx: NodeContext, builder) -> dict[str, Any]:
+        """Process each chapter's content recursively."""
+        processed = dict(data)
+        if "content" in processed and isinstance(processed["content"], list):
+            chapters = []
+            for i, chapter in enumerate(processed["content"]):
+                if isinstance(chapter, dict):
+                    chapter_processed = {}
+                    for key, value in chapter.items():
+                        if key in ("title",):
+                            chapter_processed[key] = value
+                        else:
+                            chapter_processed[key] = builder.process_node(
+                                value, ctx.child(f"chapter-{i}")
+                            )
+                    chapters.append(chapter_processed)
+                else:
+                    chapters.append(chapter)
+            processed["content"] = chapters
+        return processed
+
+    def render(self, data: dict[str, Any], ctx: NodeContext, builder) -> str:
+        template = builder.jinja_env.get_template(self.template)
+        return template.module.render_chapters(
+            data,
+            data.get("content", []),
+            ctx.depth,
+        )

webifier_extensions-1.0.1/webifier_extensions/comments/extension.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from webifier.core.extensions import Extension
+
+
+class CommentsExtension(Extension):
+    id = "webifier.comments"
+    config_key = "comments"
+    renderers = {
+        "comments": "webifier_extensions.comments.renderer.CommentsRenderer",
+    }

webifier_extensions-1.0.1/webifier_extensions/comments/renderer.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from webifier.core.base import NodeContext, RendererModule
+
+
+class CommentsRenderer(RendererModule):
+    """Render an Utterances comment widget."""
+
+    template: ClassVar[str] = "macros/comments.html"
+    META_KEYS: ClassVar[frozenset[str]] = frozenset(
+        {
+            "kind",
+            "template",
+            "label",
+            "background",
+            "style",
+            "repo",
+            "issue_term",
+            "issue_label",
+            "theme",
+            "crossorigin",
+        }
+    )
+
+    def process(self, data: dict[str, Any], ctx: NodeContext, builder) -> dict[str, Any]:
+        """No children to process — just pass config through."""
+        # Inject global config for repo fallback
+        data["_config"] = builder.config
+        return data
+
+    def render(self, data: dict[str, Any], ctx: NodeContext, builder) -> str:
+        template = builder.jinja_env.get_template(self.template)
+        return template.module.render_comments(data, data.get("_config"))

webifier_extensions-1.0.1/webifier_extensions/markdown/extension.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from webifier.core.extensions import Extension, ExtensionContext
+
+
+class MarkdownExtension(Extension):
+    id = "webifier.markdown"
+    renderers = {
+        "markdown": "webifier_extensions.markdown.renderer.MarkdownRenderer",
+    }
+
+    def register(self, ctx: ExtensionContext) -> None:
+        super().register(ctx)
+        for key in (".md", ".markdown", "md", "markdown"):
+            ctx.register_content_renderer(key, self.build_markdown_page)
+
+    def build_markdown_page(self, builder, src: str, ctx):
+        return builder._build_markdown_page(src, ctx)

webifier_extensions-1.0.1/webifier_extensions/markdown/renderer.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from webifier.core.base import NodeContext, RendererModule
+
+
+class MarkdownRenderer(RendererModule):
+    """Render a markdown string to HTML."""
+
+    template: ClassVar[str] = ""  # No template — direct render
+    META_KEYS: ClassVar[frozenset[str]] = frozenset({"kind", "template"})
+
+    def process(self, data: dict[str, Any], ctx: NodeContext, builder) -> dict[str, Any]:
+        return data
+
+    def render(self, data: dict[str, Any], ctx: NodeContext, builder) -> str:
+        """Render markdown content to HTML string."""
+        raw = data.get("content", "")
+        if not raw:
+            return ""
+        return builder.render_markdown(
+            raw,
+            assets_src_dir=ctx.assets_src_dir,
+            assets_target_dir=ctx.assets_target_dir,
+            search_links=ctx.search_links,
+        )

webifier_extensions-1.0.1/webifier_extensions/notebook/converter.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import os
+
+from webifier.core.frontmatter import split_yaml_front_matter
+
+
+def convert_notebook(builder, src: str, assets_dir: str) -> tuple[str, dict]:
+    """Convert a Jupyter notebook to HTML body content.
+
+    Uses nbconvert to export, then extracts the notebook container
+    and post-processes HTML for asset resolution.
+    """
+    from bs4 import BeautifulSoup
+
+    try:
+        from nbconvert import HTMLExporter
+    except ImportError as exc:
+        raise ImportError(
+            "nbconvert is required for notebook conversion. Install it with: pip install nbconvert"
+        ) from exc
+
+    notebook, metadata = read_notebook_with_metadata(src)
+
+    exporter = HTMLExporter()
+    body, _ = exporter.from_notebook_node(notebook)
+
+    # Extract just the notebook content
+    soup = BeautifulSoup(body, "html.parser")
+    container = soup.find(id="notebook-container") or soup.find("body") or soup
+    content = str(container)
+
+    # Post-process HTML for asset resolution
+    from webifier.core.html import process_html
+
+    content = process_html(
+        builder,
+        content,
+        assets_src_dir=os.path.dirname(src),
+        assets_target_dir=assets_dir,
+    )
+
+    return content, metadata
+
+
+def read_notebook_with_metadata(src: str) -> tuple[object, dict]:
+    import nbformat
+
+    with open(src) as f:
+        notebook = nbformat.read(f, as_version=4)
+
+    cells = notebook.get("cells", [])
+    if not cells or cells[0].get("cell_type") != "markdown":
+        return notebook, {}
+
+    metadata, first_cell_body = split_yaml_front_matter(cells[0].get("source", ""))
+    if not metadata:
+        return notebook, {}
+    if first_cell_body.strip():
+        cells[0]["source"] = first_cell_body.lstrip("\n")
+    else:
+        notebook["cells"] = cells[1:]
+    return notebook, metadata

webifier_extensions-1.0.1/webifier_extensions/notebook/extension.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import os
+
+from webifier.core.base import resolve_renderer
+from webifier.core.extensions import Extension, ExtensionContext
+from webifier.interface.io import prepend_baseurl, strip_suffixes
+
+from .converter import convert_notebook
+
+
+class NotebookExtension(Extension):
+    id = "webifier.notebook"
+    dependencies = ("webifier.standard",)
+
+    def register(self, ctx: ExtensionContext) -> None:
+        super().register(ctx)
+        for key in (".ipynb", "notebook"):
+            ctx.register_content_renderer(key, self.build_notebook_page)
+
+    def build_notebook_page(self, builder, src: str, ctx):
+        if not os.path.isfile(src):
+            print(f"  Warning: notebook file not found: {src}")
+            return None
+
+        try:
+            body_html, metadata = convert_notebook(builder, src, builder.assets_dir)
+        except Exception as exc:
+            print(f"  Warning: notebook conversion failed for {src}: {exc}")
+            return None
+
+        renderer = resolve_renderer("content-page", jinja_env=builder.jinja_env)
+        page_data = {
+            "content": body_html,
+            "metadata": metadata,
+            "title": metadata.get("title", os.path.basename(src)),
+            "page_url": prepend_baseurl(
+                strip_suffixes(src, builder._content_suffixes()),
+                builder.base_url,
+            ),
+            "source_path": src,
+        }
+        if builder.root_data:
+            page_data["nav"] = builder.root_data.get("nav")
+            page_data["footer"] = builder.root_data.get("footer")
+            page_data["config"] = builder.config
+        if builder.repo_full_name:
+            nb_dir = os.path.dirname(src)
+            nb_name = strip_suffixes(os.path.basename(src), [".ipynb"])
+            page_data["colab"] = (
+                f"https://colab.research.google.com/github/"
+                f"{builder.repo_full_name}/blob/master/{nb_dir}/{nb_name}.ipynb"
+            )
+        return renderer.render(page_data, ctx, builder)

webifier_extensions-1.0.1/webifier_extensions/people/extension.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from webifier.core.extensions import Extension
+
+
+class PeopleExtension(Extension):
+    id = "webifier.people"
+    dependencies = ("webifier.standard",)
+    renderers = {
+        "people": "webifier_extensions.people.renderer.PeopleRenderer",
+    }

webifier_extensions-1.0.1/webifier_extensions/people/renderer.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from webifier.core.base import NodeContext, RendererModule
+
+
+class PeopleRenderer(RendererModule):
+    """Render a grid of people cards."""
+
+    template: ClassVar[str] = "macros/people.html"
+    META_KEYS: ClassVar[frozenset[str]] = frozenset(
+        {
+            "kind",
+            "template",
+            "label",
+            "background",
+            "style",
+            "content",
+        }
+    )
+
+    def process(self, data: dict[str, Any], ctx: NodeContext, builder) -> dict[str, Any]:
+        """Process each person entry."""
+        processed = dict(data)
+        if "content" in processed and isinstance(processed["content"], list):
+            people = []
+            for person in processed["content"]:
+                if isinstance(person, dict):
+                    person = _process_person(person, ctx, builder)
+                people.append(person)
+            processed["content"] = people
+        return processed
+
+    def render(self, data: dict[str, Any], ctx: NodeContext, builder) -> str:
+        template = builder.jinja_env.get_template(self.template)
+        return template.module.render_people(data)
+
+
+def _process_person(person: dict, ctx: NodeContext, builder) -> dict:
+    """Process a single person dict — resolve images, render bio."""
+    # Resolve profile image
+    if "image" in person:
+        img = person["image"]
+        if isinstance(img, str) and not img.startswith(("http", "data:")):
+            new_path = builder.files.copy_file(
+                img,
+                img,
+                src_dir=ctx.assets_src_dir,
+                target_dir=ctx.assets_target_dir or builder.assets_dir,
+            )
+            if new_path:
+                person["image"] = new_path
+        elif "github" in person:
+            person["image"] = f"https://github.com/{person['github']}.png"
+
+    # GitHub-derived image fallback
+    if "image" not in person and "github" in person:
+        person["image"] = f"https://github.com/{person['github']}.png"
+
+    # Render bio as markdown
+    if "bio" in person and isinstance(person["bio"], str):
+        person["bio"] = builder.render_markdown(
+            person["bio"],
+            assets_src_dir=ctx.assets_src_dir,
+            assets_target_dir=ctx.assets_target_dir,
+        )
+
+    # Process contact links
+    if "contact" in person and isinstance(person["contact"], list):
+        processed_links = []
+        for link in person["contact"]:
+            if isinstance(link, dict):
+                link = builder._process_link(link, ctx)
+            processed_links.append(link)
+        person["contact"] = processed_links
+
+    return person

webifier_extensions-1.0.1/webifier_extensions/registry.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from .analytics.google.extension import GoogleAnalyticsExtension
+from .chapters.extension import ChaptersExtension
+from .comments.extension import CommentsExtension
+from .markdown.extension import MarkdownExtension
+from .notebook.extension import NotebookExtension
+from .people.extension import PeopleExtension
+from .resume.extension import ResumeExtension
+from .search.extension import SearchExtension
+from .standard.extension import StandardExtension
+from .theme.extension import ThemeExtension
+
+EXTENSIONS = {
+    "webifier.standard": StandardExtension,
+    "webifier.markdown": MarkdownExtension,
+    "webifier.notebook": NotebookExtension,
+    "webifier.search": SearchExtension,
+    "webifier.theme": ThemeExtension,
+    "webifier.analytics.google": GoogleAnalyticsExtension,
+    "webifier.comments": CommentsExtension,
+    "webifier.people": PeopleExtension,
+    "webifier.chapters": ChaptersExtension,
+    "webifier.resume": ResumeExtension,
+}