From ffa7200a6ee181e2c3fdd282a401d43db1076b74 Mon Sep 17 00:00:00 2001
From: Leo Vasanko <git@vasanko.com>
Date: Fri, 28 Aug 2026 00:25:10 +0000
Subject: [PATCH] Automatic navigational cards on index pages, replacing the
 sidebar menu.

---
 docs/backend.md                  |   4 +-
 docs/content-model.md            |   2 +-
 docs/design-principles.md        |   4 +-
 frontend/src/assets/pagerite.css | 117 +++++++++++++++++++++
 pagerite/views.py                | 168 ++++++++++++++++++++++++-------
 5 files changed, 252 insertions(+), 43 deletions(-)

diff --git a/docs/backend.md b/docs/backend.md
index 78f84a5..0b1e90d 100644
--- a/docs/backend.md
+++ b/docs/backend.md
@@ -26,7 +26,9 @@ The shared page layout as an html5tagger `Template` with placeholders (`Title`,
 
 Content pages get SEO/social meta (description, canonical link, Open Graph + twitter card) from heuristics over the rendered article: the description is the first paragraph's text, the share image prefers a `{.hero}`-classed image, then the first raster `<img>`, then the first SVG; the first `<video>` yields `og:video`; URLs are made absolute with the site origin (`Data.site_url` — learned from admin browsers reporting their `location.origin` via `POST /_api/site-url`, correct even behind reverse proxies; until learned, the request's own base URL is the fallback); `article:published/modified_time` come from `Node.created`/`modified`. If the markdown contains its own h1, the page title is NOT rendered as an additional h1 (it still supplies `<title>` and nav labels).
 
-The navbar holds top-level items only; the current section's subitems go to a left `#sidebar` as a nested list (the section's direct children plain, deeper levels indented with article-list-style markers), which is rendered when the section offers at least two published items, or exactly one while viewing anything other than that only page — the section index, a 404, a grandchild (so those pages can reach the child), and also on that only page itself when it has published children of its own; no aside element at all on the front page, leaf pages and the sole childless page of a one-page section. Also, category labels are nodes without content — None *or* empty markdown — and their nav links point at their first child page. Dynamic regions have stable ids (`#page-banner`, `#nav`, `#sidebar`, `#main`) for fetch-navigation swaps (`#sidebar` may be absent on either side of a swap).
+The navbar holds top-level items only; the current section's subitems go to a left `#sidebar` as a nested list (the section's direct children plain, deeper levels indented with article-list-style markers), rendered only from the second level down — main-level pages list their children as cards after the content instead. Below that, the sidebar renders when the section offers at least two published items, or exactly one while viewing anything other than that only page — the section index, a 404, a grandchild (so those pages can reach the child), and also on that only page itself when it has published children of its own; no aside element at all on the front page, main-level pages, leaf pages and the sole childless page of a one-page section. Also, category labels are nodes without content — None *or* empty markdown — and their nav links point at their first child page. Dynamic regions have stable ids (`#page-banner`, `#nav`, `#sidebar`, `#main`) for fetch-navigation swaps (`#sidebar` may be absent on either side of a swap).
+
+Any page with published children — a category page — lists them as a card grid (`nav.cards`) after the markdown content, as does the content-less category 404. Each card links to the child page (a content-less child to its first leaf) and shows the child's share image (the same hero → first raster → first SVG heuristics as `og:image`) as a full-card cover with the title overlaid.
 
 ## `seed.py`
 
diff --git a/docs/content-model.md b/docs/content-model.md
index b1d926f..bbb79ca 100644
--- a/docs/content-model.md
+++ b/docs/content-model.md
@@ -6,7 +6,7 @@ The site structure is stored in the kanta database managed by `pagerite/data.py`
 
 `Data.menu` maps top-level slugs to `Node`s, each with `children` keyed by slug — the URL path is the slug chain. The front page is whichever top-level node has slug "" (parallel to the other main level pages, not their parent); it cannot have children, and renaming its slug away leaves no front page ("/" redirects to the first nav item).
 
-`Node.content` is the Markdown page, or None for a pure category label whose URL renders a placeholder page (while nav links to it point at its first child); every label's title and slug are editable.
+`Node.content` is the Markdown page, or None for a pure category label whose URL renders a 404 listing its children as cards (while nav links to it point at its first child); every label's title and slug are editable. A page with published children — a category page — lists them as cards after its markdown content; the sidebar sub-navigation renders only from the second level down, never on main-level pages.
 
 Siblings order by the fractional `Node.order` key: a moved item gets a fresh key relative to its new siblings, all others keep theirs. `resolve`/`find_slot` walk the tree by path; moves are slot detach/attach carrying the whole subtree. Legacy flat `Data.pages` (pre-tree databases) migrates into `menu` on startup. The app owns the `Data` object; reads are plain attribute access, writes in `kanta.transaction(...)`.
 
diff --git a/docs/design-principles.md b/docs/design-principles.md
index fd37c0f..c44da28 100644
--- a/docs/design-principles.md
+++ b/docs/design-principles.md
@@ -27,8 +27,8 @@ Pagerite is a single-user CMS/blog. This document records the initial high-level
 - All pages share one static layout, defined once as an **html5tagger Template** with capitalized placeholders (`Title`, `Banner`, `Nav`, `Sidebar`, `Main`) filled per request. The dynamic regions carry stable ids (`#page-banner`, `#nav`, `#sidebar`, `#main`).
 - The page top is a **full-width banner header** with the site name and the navigation bar overlaid on it — no separate chrome header. The banner combines two layers, stacked in `#page-banner` (a grid, so they overlay): first the **banner design** — a named design living in a theme folder (`pagerite/themes/{name}/banner.css` plus artwork as `banner.html` — arbitrary markup like canvas + style + script — or `banner.svg`), chosen per page via `Node.banner_design` (a design name, "" for none, None to inherit from the nearest ancestor, then the front page, then the active theme's own design). The artwork is inlined into a `div[data-design]` wrapper: SVG artwork can be recolored from the theme stylesheet (corporate's single SVG serves both light and dark mode via `var()`-driven stops). Second, **per-page author code**: `Node.banner` holds an arbitrary trusted HTML snippet (an image, a styled div, canvas + script — anything), resolved by walking up the node's ancestors to the front page and rendered **after** the design artwork, so author styles always win over the design's own. The base stylesheet falls back to a plain gradient. There is deliberately no scrim fading the banner into the page background — any such fade would ruin user-supplied designs; themes that want one bake it into their SVG (purple does).
 - **Fetch-navigation.** Links are plain `<a href>`; a small script (`frontend/src/pagerite.js`) intercepts same-origin clicks, fetches the page, and swaps the `#page-banner`, `#nav`, `#sidebar` and `#main` regions, the document title, and the site-wide custom CSS (`<style id="pagerite-user">` in `<head>`), keeping the rest of `<head>` and the layout chrome. Without JS everything works as normal page loads. Scripts inside fetched banner and content regions are re-created so they execute. Swaps run inside `document.startViewTransition` for a rotating cube page transition (CSS adapted from termotohtori.fi — the `::view-transition*` block is fragile, do not tweak; skipped under `prefers-reduced-motion`). Navigation within the same top-level section crossfades instead of rotating; browser back navigation rotates in reverse.
-- **The site structure is a tree of labels.** `Data.menu` holds the top-level items by slug, each with `children` keyed by slug — the URL path is the slug chain. The front page is a top-level node with slug "" (an item *parallel* to the other main level pages, not their parent) and cannot have children. The header navbar holds only the top level; a top-level item is highlighted when viewing any of its subpages. When the current page is inside a main level section with children, those direct children are listed in a **left sidebar** (`#sidebar`), one level deep. The sidebar exists only when there is something to navigate — sections with fewer than two published items, leaf pages and the front page render no aside element at all. Other sections' subitems are never shown without navigating into them first.
-- **Landing pages are optional.** Every label can either have content (`Node.content`, a Markdown page) or none — a content-less label renders a placeholder page (404 with a pen to create it) instead of redirecting, while nav links to it point straight at its first child, so categories need no filler content and normal navigation never sees the placeholder. Title and slug of every label are editable; renaming a slug moves the whole subtree. The sidebar never lists the section itself, avoiding title duplication with the navbar.
+- **The site structure is a tree of labels.** `Data.menu` holds the top-level items by slug, each with `children` keyed by slug — the URL path is the slug chain. The front page is a top-level node with slug "" (an item *parallel* to the other main level pages, not their parent) and cannot have children. The header navbar holds only the top level; a top-level item is highlighted when viewing any of its subpages. A page with published children lists them as **cards** after its content (the child page's share image as the cover, like the og tags, with the title overlaid); a **left sidebar** (`#sidebar`) with the section's sub-navigation appears only from the second level down, when there is something to navigate — main-level pages, sections with fewer than two published items, leaf pages and the front page render no aside element at all. Other sections' subitems are never shown without navigating into them first.
+- **Landing pages are optional.** Every label can either have content (`Node.content`, a Markdown page) or none — a content-less label renders a 404 page listing its children as cards (with a pen to create the landing page) instead of redirecting, while nav links to it point straight at its first child, so categories need no filler content and normal navigation never sees the 404. Title and slug of every label are editable; renaming a slug moves the whole subtree. The sidebar never lists the section itself, avoiding title duplication with the navbar.
 - **Menu order is manual.** Each node has a fractional `order` key among its siblings; reordering/moving writes only the moved node (it takes a fresh value halfway between its new siblings; all other items keep theirs). New pages append at the end of their menu. Structure edits (reorder, move/rename with the whole subtree, retitle) go through `POST /_api/structure` and the editor's structure panel.
 - Unpublished pages are hidden from both nav and URL access (404).
 
diff --git a/frontend/src/assets/pagerite.css b/frontend/src/assets/pagerite.css
index 4075eda..49ee33f 100644
--- a/frontend/src/assets/pagerite.css
+++ b/frontend/src/assets/pagerite.css
@@ -438,6 +438,121 @@ main {
   container-type: inline-size;
 }
 
+/* Child-entry card stacks: a category page (and the content-less category
+   404) lists its published children after the markdown content — one column
+   per child, the child's whole subtree flattened into the column in menu
+   order (see _cards in views.py). The row bleeds to full page width
+   (div.wide): the columns first grow to fill it, then shrink rather than
+   wrap. Every card has the same fixed 16/10 shape, covered entirely by the
+   page's share image (og:image heuristics, as a background — a gradient
+   placeholder when it has none) with the title overlaid on a translucent
+   band at the bottom. The card is one <a> holding only phrasing-level
+   spans; the spans lay out as blocks. */
+.cards {
+  display: flex;
+  /* Stacks stop growing at their cap; center the row in the bleed then. */
+  justify-content: center;
+  gap: 1.25rem;
+  margin-top: 2.5rem;
+  /* The full-bleed breakout (div.wide rules) lands the edges exactly on the
+     viewport's; this keeps the cards themselves off the edges. */
+  padding-inline: 1.25rem;
+}
+
+.cards .stack {
+  /* Grow to fill the row (up to the cap — full-width rows would make huge
+     cards), shrink (not wrap) when there are too many. */
+  flex: 1 1 0;
+  max-width: 24rem;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 1.25rem;
+}
+
+/* Phones: the columns stack vertically instead of shrinking to slivers.
+   Text-only cards (gradient cover + description) then fit their content —
+   the fixed 16/10 shape only makes sense for image covers. */
+@media (max-width: 48rem) {
+  .cards {
+    flex-direction: column;
+  }
+
+  .card:has(.desc) {
+    aspect-ratio: auto;
+  }
+}
+
+.card {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  aspect-ratio: 16 / 10;
+  /* Allow shrinking below the text's min-content width: without this the
+     text cards hold their stack wider than the image-only stacks. */
+  min-width: 0;
+  overflow: hidden;
+  border: 1px solid var(--line);
+  border-radius: 0.5rem;
+  background: var(--surface);
+  color: var(--text);
+  text-decoration: none;
+  transition: transform 0.2s, box-shadow 0.2s;
+  box-shadow: 0 0 0.1rem black;
+}
+
+.card:hover {
+  transform: scale(1.02);
+  box-shadow: 0 0 0.3rem black;
+}
+
+/* The cover fills the whole card; the text spans are positioned so they
+   paint above it. */
+.card .cover {
+  position: absolute;
+  inset: 0;
+  background: linear-gradient(135deg, var(--surface), var(--bg));
+  background-size: cover;
+  background-position: center;
+}
+
+.card .title {
+  position: relative;
+  display: block;
+  margin-top: auto;
+  padding: 0.75rem 1.25rem 0.9rem;
+  background: color-mix(var(--bg) 40%, transparent);
+  /* Pinned: the article a:hover accent must not leak through the card. */
+  color: var(--text);
+  font-family: var(--font-heading);
+  font-size: 1.25rem;
+  font-weight: 900;
+  line-height: 1.25;
+}
+
+/* Image-less cards carry the description under the title, extending the
+   same translucent band. */
+.card .title:has(+ .desc) {
+  padding-bottom: 0;
+}
+
+.card .desc {
+  position: relative;
+  display: block;
+  overflow: hidden;
+  /* Four lines exactly: the text itself is truncated server-side (_cards),
+     this is just the safety net. max-height spans the lines plus the
+     vertical padding (border-box), so nothing bleeds past the clip. */
+  line-height: 1.4;
+  max-height: calc(4 * 1.4em + 1.3rem);
+  padding: 0.4rem 1.25rem 0.9rem;
+  background: color-mix(var(--bg) 30%, transparent);
+  color: var(--muted);
+  font-size: 0.95rem;
+  text-align: left;
+  hyphens: none;
+}
+
 article h1,
 article h2,
 article h3,
@@ -1102,6 +1217,7 @@ pre.wide {
    Multicol pages measure the bleed from main instead (cqw rules below),
    which insets for the editor automatically. */
 body.editing figure:has(.wide),
+body.editing div.wide,
 body.editing pre.wide {
   width: calc(100vw - var(--editor-w));
   margin-inline: calc(50% - (100vw - var(--editor-w)) / 2);
@@ -1118,6 +1234,7 @@ body.editing pre.wide {
    are below.) */
 @media (max-width: 102rem) {
   body:has(#sidebar):not(.editing):not(:has(.multicol)) figure:has(.wide),
+  body:has(#sidebar):not(.editing):not(:has(.multicol)) div.wide,
   body:has(#sidebar):not(.editing):not(:has(.multicol)) pre.wide {
     margin-inline: -13.25rem 0;
   }
diff --git a/pagerite/views.py b/pagerite/views.py
index 86720f2..2aa3690 100644
--- a/pagerite/views.py
+++ b/pagerite/views.py
@@ -8,10 +8,11 @@ can swap them without reloading the page chrome.
 Navigation walks the Node tree directly (see data.py): nav_html lists the
 top level — the front page (slug "") is an ordinary top-level item, not
 the parent of the others — and sidebar_html the sub-navigation of the
-current top-level section, rendered only when the section offers at
-least two published items. Nodes without content are category labels; nav links
+current top-level section, rendered only from the second level down
+(main-level pages list their children as cards after the content instead,
+see page_content). Nodes without content are category labels; nav links
 to them point straight at their first child page (first_leaf), and their
-own URL renders a placeholder page (render_category).
+own URL renders a card-listing page (render_category, a 404).
 """
 
 from pathlib import Path
@@ -332,17 +333,19 @@ def sidebar_html(menu: dict[str, Node], current: str) -> HTML:
     The sidebar is the current main level section's sub-navigation: the
     section's direct children as the top list level, with each item's own
     published children nested under it (third level and deeper), so it
-    exists only when there is something to navigate: the section must
-    offer at least two published items, or exactly one while viewing
-    anything else than that only page — the section index, a 404, a
-    grandchild (otherwise those pages offer no way to reach the child) —
-    and viewing that only page itself still shows the sidebar when the
-    page has published children of its own to reach.
-    The front page, leaf pages, the sole childless page of a one-page
-    section and childless sections get no aside element at all (rather
-    than an empty or useless one-item box).
+    exists only when there is something to navigate. It renders only from
+    the second level down: main-level pages (and the front page) list
+    their children as cards after the content instead of a sidebar. From
+    there, the section must offer at least two published items, or exactly
+    one while viewing anything else than that only page — the section
+    index, a 404, a grandchild (otherwise those pages offer no way to
+    reach the child) — and viewing that only page itself still shows the
+    sidebar when the page has published children of its own to reach.
+    Leaf pages, the sole childless page of a one-page section and
+    childless sections get no aside element at all (rather than an empty
+    or useless one-item box).
     """
-    if not current:
+    if not current or "/" not in current:
         return HTML("")
     section = current.split("/", 1)[0]
     node = menu.get(section)
@@ -511,7 +514,11 @@ def banner_source(menu: dict[str, Node], path: str) -> str | None:
 
 
 def page_content(menu: dict[str, Node], path: str) -> HTML:
-    """Render the contents of the #main element for a page."""
+    """Render the contents of the #main element for a page.
+
+    A page with published children (a category page) lists them as cards
+    after the markdown content.
+    """
     node = resolve(menu, path)[-1]
     rendered = render(node.content or "", path, node.created, node.modified)
     # Long articles get .multicol: the article column cap lifts (see the
@@ -525,9 +532,69 @@ def page_content(menu: dict[str, Node], path: str) -> HTML:
         if not has_h1(node.content or ""):
             doc.h1(node.title)
         doc.div(HTML(rendered.html), class_="body")
+        _cards(doc, menu, node, path)
     return HTML(str(doc))
 
 
+def _cards(doc, menu: dict[str, Node], node: Node, path: str) -> None:
+    """Card stacks of the node's published children (nothing when childless).
+
+    One column per direct child, all in a single full-width row (the .wide
+    breakout): the columns grow to fill the page and shrink rather than
+    wrap. A column holds the child's whole subtree flattened in menu order
+    — nesting levels are not split out — starting with the first page that
+    has actual content (the child itself when it does, its first leaf
+    otherwise, recursively). Each card is one <a> showing the page's share
+    image (the same heuristics as og:image) as the cover and its title;
+    image-less cards get a gradient cover and also show the description.
+    Only phrasing-level elements (spans) go inside the <a>: as a formatting
+    element it would be cloned by the HTML parser around any block-level
+    child, splitting one card into several links.
+    """
+    items = [(s, c) for s, c in sorted_nodes(node.children) if c.published]
+    if not items:
+        return
+    with doc.div(class_="cards wide"):
+        for slug, child in items:
+            cpath = f"{path}/{slug}" if path else slug
+            entries = list(_walk(child, cpath))
+            if not entries:
+                continue
+            with doc.div(class_="stack"):
+                for epath, enode in entries:
+                    _card(doc, enode, epath)
+
+
+def _walk(node: Node, path: str):
+    """Published content pages of a subtree, pre-order in menu order: the
+    node itself first when it has content (the stack's landing card), then
+    its descendants (content-less nodes contribute only their subtree)."""
+    if node.content:
+        yield path, node
+    for slug, child in sorted_nodes(node.children):
+        if child.published:
+            yield from _walk(child, f"{path}/{slug}")
+
+
+def _card(doc, node: Node, path: str) -> None:
+    """One card in a stack: cover + title, plus the description when the
+    page has no image (its card shows a gradient cover instead)."""
+    image = description = ""
+    if node.content:
+        html = render(node.content, path, node.created, node.modified).html
+        image, _ = _media(html)
+        if not image:
+            description = _description(html, 150)
+    with doc.a(href=f"/{path}", class_="card"):
+        if image:
+            doc.span(class_="cover", style=f'background-image: url("{image}")')
+        else:
+            doc.span(class_="cover")
+        doc.span(_title(path.rpartition("/")[2], node), class_="title")
+        if description:
+            doc.span(description, class_="desc")
+
+
 _FIRST_P = re.compile(r"<p[^>]*>(.*?)</p>", re.S)
 _TAG = re.compile(r"<[^>]+>")
 _IMG_TAG = re.compile(r"<img\b[^>]*>")
@@ -536,23 +603,34 @@ _ATTR_SRC = re.compile(r'src="([^"]+)"')
 _ATTR_CLASS = re.compile(r'class="([^"]*)"')
 
 
-def _share_media(html: str, base_url: str) -> tuple[str, str]:
-    """(image, video) share URLs from the rendered article.
+_SENTENCE_END = re.compile(r"[.!?][”'\")]*(?=\s|$)")
+
+
+def _description(html: str, limit: int = 200) -> str:
+    """Article description: the first paragraph's text, truncated at a
+    sentence end (or, failing that, a word boundary) within ``limit``.
+    Used for og:description."""
+    m = _FIRST_P.search(html)
+    text = unescape(_TAG.sub("", m.group(1) if m else ""))
+    text = " ".join(text.split())
+    if len(text) <= limit:
+        return text
+    # Prefer a clean cut: the last sentence ending within the limit, as
+    # long as it does not reduce the description to a tiny fragment.
+    if (end := max((m.end() for m in _SENTENCE_END.finditer(text[:limit])), default=0)) > limit // 2:
+        return text[:end]
+    return text[:limit].rsplit(" ", 1)[0] + "…"
+
+
+def _media(html: str) -> tuple[str, str]:
+    """Raw (image, video) srcs from rendered article HTML (relative ok).
 
     Image preference: an image with class "hero" (author override, may
     appear anywhere in the article), then the first raster image (SVGs
     rasterize poorly or not at all on many social scrapers), then the
     first SVG. Video: the first <video> — og:video is in the OGP spec and
-    honored mainly by Facebook; X/Twitter ignores it. Absolute URLs are
-    built from the request base, scrapers cannot use relative ones.
+    honored mainly by Facebook; X/Twitter ignores it.
     """
-    if not base_url:
-        return "", ""
-
-    def absolute(src: str) -> str:
-        src = unescape(src)
-        return src if src.startswith(("http://", "https://")) else f"{base_url}{src}"
-
     hero = raster = svg = video = ""
     for tag in _IMG_TAG.findall(html):
         if not (src := _ATTR_SRC.search(tag)):
@@ -571,7 +649,23 @@ def _share_media(html: str, base_url: str) -> tuple[str, str]:
         if m := _ATTR_SRC.search(tag):
             video = m.group(1)
             break
-    image = hero or raster or svg
+    return hero or raster or svg, video
+
+
+def _share_media(html: str, base_url: str) -> tuple[str, str]:
+    """(image, video) share URLs from the rendered article.
+
+    The _media picks as absolute URLs built from the request base —
+    social scrapers cannot use relative ones.
+    """
+    if not base_url:
+        return "", ""
+
+    def absolute(src: str) -> str:
+        src = unescape(src)
+        return src if src.startswith(("http://", "https://")) else f"{base_url}{src}"
+
+    image, video = _media(html)
     return (absolute(image) if image else "", absolute(video) if video else "")
 
 
@@ -587,11 +681,7 @@ def _social_meta(
     (social scrapers cannot use relative ones).
     """
     url = f"{base_url}/{path}" if base_url else ""
-    m = _FIRST_P.search(html)
-    text = unescape(_TAG.sub("", m.group(1) if m else ""))
-    text = " ".join(text.split())
-    if len(text) > 200:
-        text = text[:200].rsplit(" ", 1)[0] + "…"
+    text = _description(html)
     image, video = _share_media(html, base_url)
     return {
         "description": text,
@@ -648,20 +738,20 @@ def render_category(
     favicon: str = "",
     brand_html: str = "",
 ) -> str:
-    """Render the placeholder for a content-less category label (404).
+    """Render the listing for a content-less category label (404).
 
-    The node exists in the tree but has no page of its own. Nav links
-    point straight at its first child, so this is mainly seen in the site
-    editor, where the pen creates the landing page.
+    The node exists in the tree but has no page of its own: its published
+    children are listed as cards, like on a category page with content.
+    Nav links point straight at the first child, so this is mainly seen
+    in the site editor, where the pen creates the landing page.
     """
     node = resolve(menu, path)[-1]
     title = _title(path.rpartition("/")[2], node)
-    sidebar = sidebar_html(menu, path)
     doc = E.article
     with doc:
         doc.h1(title)
-        if sidebar:
-            doc.p("Pages in this section are listed in the menu on the left.")
+        if any(c.published for c in node.children.values()):
+            _cards(doc, menu, node, path)
         else:
             doc.p("This section has no page of its own yet.")
     return str(
@@ -669,7 +759,7 @@ def render_category(
             Title=f"{title} – {brand}" if brand else title,
             Brand=_brand_link(brand, brand_html),
             Nav=nav_html(menu, path),
-            Sidebar=sidebar,
+            Sidebar=sidebar_html(menu, path),
             Banner=banner_html(menu, path, theme),
             Main=HTML(str(doc)),
         ),