podpack-pages 0.2.0__tar.gz

podpack_pages-0.2.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.3
+Name: podpack-pages
+Version: 0.2.0
+Summary: Content pages for podpack sites: one name space, Markdown first, HTML second
+Author: Steve Holden
+Author-email: Steve Holden <steve@holdenweb.com>
+Requires-Dist: flask>=3.0
+Requires-Dist: markdown>=3.5.2
+Requires-Dist: python-markdown-math>=0.8
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# podpack-pages
+
+A podpack app serving a site's prose content — Markdown and HTML files — from
+a **single name space**. `/pages/<name>` searches the Markdown tree
+(`md-pages/<name>.md`) first and the HTML tree (`html-pages/<name>.html`)
+second, so a page's address never says which format it is stored in, and a
+Markdown page shadows an HTML one of the same name.
+
+Three spellings, per podpack convention: the distribution is `podpack-pages`,
+the import name (for a site's `apps` list) is `podpack_pages`, and the app
+answers to `pages` — its blueprint's name, which keys `[apps.pages]`,
+`[site.mounts]` and its directories on disk.
+
+## Content location
+
+Content lives in the app's host data directory:
+
+```
+<data root>/pages/md-pages/       Markdown, searched first
+<data root>/pages/html-pages/     HTML, searched second; assets live beside pages
+```
+
+The package ships a starter `data/` tree which podpack seeds to the host on
+first install, so editing a page on the host changes the site with no rebuild.
+
+## Routes
+
+| Route | What it does |
+| --- | --- |
+| `/pages/<name>` | serve the page, Markdown space first |
+| `/pages/asset/<path>` | serve an asset (image, stylesheet) belonging to a page |
+
+Relative `src`/`href` references inside HTML pages are rewritten server-side
+through `url_for("pages.asset", ...)`, so they follow the app wherever the
+site mounts it. A page named `asset/...` would be shadowed by the asset route;
+don't create one.
+
+## Markdown rendering
+
+Extensions `mdx_math` and `codehilite` are enabled. A leading `# Heading`
+becomes the page's title and is removed from the body; a page without one
+gets `[apps.pages] default_title`, or "Untitled".
+
+## Configuration
+
+```toml
+[apps.pages]
+default_title = "Just another note"     # title for Markdown pages with no heading
+```
+
+Both settings are optional; the app ships defaults.
+
+## Requirements of the site's chrome
+
+The Markdown template fills `{% block scripts %}` with MathJax. A site chrome
+that does not define that block silently drops it — mathematics then renders
+as raw TeX.

podpack_pages-0.2.0/README.md

@@ -0,0 +1,57 @@
+# podpack-pages
+
+A podpack app serving a site's prose content — Markdown and HTML files — from
+a **single name space**. `/pages/<name>` searches the Markdown tree
+(`md-pages/<name>.md`) first and the HTML tree (`html-pages/<name>.html`)
+second, so a page's address never says which format it is stored in, and a
+Markdown page shadows an HTML one of the same name.
+
+Three spellings, per podpack convention: the distribution is `podpack-pages`,
+the import name (for a site's `apps` list) is `podpack_pages`, and the app
+answers to `pages` — its blueprint's name, which keys `[apps.pages]`,
+`[site.mounts]` and its directories on disk.
+
+## Content location
+
+Content lives in the app's host data directory:
+
+```
+<data root>/pages/md-pages/       Markdown, searched first
+<data root>/pages/html-pages/     HTML, searched second; assets live beside pages
+```
+
+The package ships a starter `data/` tree which podpack seeds to the host on
+first install, so editing a page on the host changes the site with no rebuild.
+
+## Routes
+
+| Route | What it does |
+| --- | --- |
+| `/pages/<name>` | serve the page, Markdown space first |
+| `/pages/asset/<path>` | serve an asset (image, stylesheet) belonging to a page |
+
+Relative `src`/`href` references inside HTML pages are rewritten server-side
+through `url_for("pages.asset", ...)`, so they follow the app wherever the
+site mounts it. A page named `asset/...` would be shadowed by the asset route;
+don't create one.
+
+## Markdown rendering
+
+Extensions `mdx_math` and `codehilite` are enabled. A leading `# Heading`
+becomes the page's title and is removed from the body; a page without one
+gets `[apps.pages] default_title`, or "Untitled".
+
+## Configuration
+
+```toml
+[apps.pages]
+default_title = "Just another note"     # title for Markdown pages with no heading
+```
+
+Both settings are optional; the app ships defaults.
+
+## Requirements of the site's chrome
+
+The Markdown template fills `{% block scripts %}` with MathJax. A site chrome
+that does not define that block silently drops it — mathematics then renders
+as raw TeX.

podpack_pages-0.2.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "podpack-pages"
+version = "0.2.0"
+description = "Content pages for podpack sites: one name space, Markdown first, HTML second"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "flask>=3.0",
+    "markdown>=3.5.2",
+    "python-markdown-math>=0.8",
+]
+
+[[project.authors]]
+name = "Steve Holden"
+email = "steve@holdenweb.com"
+
+[build-system]
+requires = ["uv_build>=0.8.4,<0.9.0"]
+build-backend = "uv_build"
+
+# podpack is deliberately absent from `dependencies`: a real dependency's
+# [tool.uv.sources] entry travels with the distribution, so a site whose own
+# podpack source differs could never lock. A dependency group is dev-only
+# metadata and constrains nobody. See writing-an-app.md rule 1.
+[dependency-groups]
+dev = [
+    "podpack",
+    "pytest>=8.0",
+    "mypy>=1.11",
+    "types-markdown>=3.10.2.20260712",
+]
+
+[tool.uv.sources]
+podpack = { path = "/Users/sholden/sites/podpack", editable = true }
+
+[tool.mypy]
+files = ["src", "tests"]

podpack_pages-0.2.0/src/podpack_pages/__init__.py

@@ -0,0 +1,16 @@
+"""The pages app: a site's prose content, served from one name space.
+
+Content is Markdown or HTML files under the app's host data directory. A
+request names a page, not a format: the Markdown space is searched first and
+the HTML space second, so the two kinds of content share one set of addresses
+and a Markdown page shadows an HTML one of the same name.
+"""
+
+from podpack import SiteApp
+
+from .views import blueprint
+
+site_app = SiteApp(
+    blueprint=blueprint,
+    url_prefix="/pages",
+)

podpack_pages-0.2.0/src/podpack_pages/content.py

@@ -0,0 +1,94 @@
+"""Locating content on disk, and preparing HTML pages for serving.
+
+The app's data directory holds two trees, `md-pages/` and `html-pages/`,
+seeded from the package on first install. Lookup presents them as a single
+name space: `find_page("x")` tries `md-pages/x.md` before `html-pages/x.html`,
+and assets resolve the same way. Which tree a file sits in is a storage
+detail, not part of any page's address.
+"""
+
+from __future__ import annotations
+
+import mimetypes
+import re
+from collections.abc import Callable
+from pathlib import Path
+
+MD_TREE = "md-pages"
+HTML_TREE = "html-pages"
+
+_ABSOLUTE_PREFIXES = ("/", "http://", "https://", "data:", "#", "mailto:")
+
+
+class ContentNotFound(LookupError):
+    """The requested content does not exist."""
+
+
+def _check_relative(path: str) -> None:
+    """Refuse anything that could step outside the content trees."""
+    if not path or path.startswith("/"):
+        raise ContentNotFound(path)
+    for segment in path.split("/"):
+        if segment in ("", "..", "."):
+            raise ContentNotFound(path)
+
+
+def find_page(root: Path, name: str) -> tuple[str, str]:
+    """Resolve `name` in the unified space: Markdown first, then HTML.
+
+    Returns `("markdown", text)` or `("html", text)`.
+    """
+    _check_relative(name)
+    candidates = (
+        ("markdown", root / MD_TREE / f"{name}.md"),
+        ("html", root / HTML_TREE / f"{name}.html"),
+    )
+    for kind, path in candidates:
+        try:
+            return kind, path.read_text()
+        except OSError:
+            continue
+    raise ContentNotFound(name)
+
+
+def find_asset(root: Path, path: str) -> tuple[bytes, str]:
+    """Resolve an asset the same way pages resolve: Markdown tree first."""
+    _check_relative(path)
+    for tree in (MD_TREE, HTML_TREE):
+        fpath = root / tree / path
+        try:
+            body = fpath.read_bytes()
+        except OSError:
+            continue
+        ctype, _ = mimetypes.guess_type(str(fpath))
+        return body, ctype or "application/octet-stream"
+    raise ContentNotFound(path)
+
+
+# src="…" / href="…" with either quoting style. Non-greedy value match so
+# multiple attributes on the same tag don't get swallowed together.
+_ATTR_RE = re.compile(
+    r'(?P<attr>src|href)\s*=\s*(?P<q>["\'])(?P<val>[^"\']*)(?P=q)',
+    re.IGNORECASE,
+)
+
+
+def rewrite_asset_urls(html: str, page_dir: str, asset_url: Callable[[str], str]) -> str:
+    """Rewrite relative `src`/`href` values through `asset_url`.
+
+    `asset_url` maps a path relative to the content trees to a servable URL --
+    the view passes `url_for("pages.asset", ...)` so the result follows the app
+    wherever the site mounts it. Absolute URLs, anchors, `mailto:` and `data:`
+    URIs pass through unchanged. `page_dir` is the directory the page lives in
+    relative to its tree, empty at the root.
+    """
+
+    def _replace(m: re.Match[str]) -> str:
+        val = m.group("val")
+        lowered = val.lower()
+        if any(lowered.startswith(p) for p in _ABSOLUTE_PREFIXES):
+            return m.group(0)
+        target = f"{page_dir}/{val}" if page_dir else val
+        return f'{m.group("attr")}={m.group("q")}{asset_url(target)}{m.group("q")}'
+
+    return _ATTR_RE.sub(_replace, html)