From 512ed91b319e4ea5c0fb3e063923a7df32458f0c Mon Sep 17 00:00:00 2001
From: Leo Vasanko <git@vasanko.com>
Date: Wed, 19 Aug 2026 01:40:26 +0000
Subject: [PATCH] Bottom-anchor banner artwork, instant navigation via
 in-memory page cache, seed/stars/structure tweaks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Fix banner artwork sizing: explicit 100% grid track so children
  stretch instead of resolving height:100% against a content-sized row
  (SVG intrinsic ratio bloated the row, cropping the artwork's bottom).
  Bottom-anchor via object-position, transform-origin and YMax slice.
- pagerite.js: in-memory page cache — preload every visible internal
  link once, serve navigation from memory without fetching; editors'
  loadPlain keeps the cache in sync (pagerite:page-fetched).
- Structure editor: delete pages directly, no two-step confirmation.
- New 'stars' banner design (drifting starfield) alongside 'eyes'.
- Rewrite seed content: welcome page, three-level docs section covering
  all Markdown features (source + rendered), showcase hierarchy with
  image positioning and a simple leaf-page banner example.
---
 AGENTS.md                            |  11 +-
 frontend/src/StructureEditor.vue     |  22 +-
 frontend/src/StructureTree.vue       |  11 +-
 frontend/src/assets/pagerite.css     |  23 +-
 frontend/src/pagerite.js             |  63 ++--
 frontend/src/swapdoc.js              |   6 +-
 pagerite/app.py                      |  11 +-
 pagerite/seed.py                     | 417 +++++++++++++++++----------
 pagerite/themes/corporate/banner.svg |   2 +-
 pagerite/themes/nitro/banner.svg     |   2 +-
 pagerite/themes/purple/banner.svg    |   2 +-
 pagerite/themes/stars/banner.css     |   7 +
 pagerite/themes/stars/banner.html    |  52 ++++
 pagerite/themes/summer/banner.svg    |   2 +-
 14 files changed, 409 insertions(+), 222 deletions(-)
 create mode 100644 pagerite/themes/stars/banner.css
 create mode 100644 pagerite/themes/stars/banner.html

diff --git a/AGENTS.md b/AGENTS.md
index 99ca732..5535aed 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -129,7 +129,12 @@ not for the public pages. See `docs/design-principles.md` for the design.
     created, via a `@kanta.bootstrap` handler in `app.py`.
   - `frontend/src/` — the Vue editor and public-page entries.
     - `main.js` — Vue editor app entry, mounts the tabbed EditorShell.
-    - `pagerite.js` — public page entry; runs fetch-navigation, scroll-reveal,
+    - `pagerite.js` — public page entry; runs fetch-navigation (backed by an
+      in-memory page cache: every visible internal link — and the current
+      page — is fetched once at load, clicks are then served from JS with no
+      fetch, and the editors' `loadPlain` keeps the cache current via a
+      `pagerite:page-fetched` event; articles are `cache-control: no-cache`
+      on the wire), scroll-reveal,
       OverlayScrollbars on `document.body` (floating, auto-hiding scrollbars
       that never reserve layout space or shift the page when appearing;
       native scroll APIs like `window.scrollTo` keep working; themed via the
@@ -174,7 +179,9 @@ not for the public pages. See `docs/design-principles.md` for the design.
       gradient brand, flower bullets, and a layered-parallax banner (sun
       rises, clouds drift, nearer hills move less) with idle animations
       (swaying flowers, floating clouds, breathing sun glow) wrapped in
-      `prefers-reduced-motion: no-preference`) and the
+      `prefers-reduced-motion: no-preference`); standalone banner designs
+      (no theme.css) ship as `eyes` (a canvas critter in the grass) and
+      `stars` (a drifting starfield)) and the
       companion `banner.css` banner designs are served by the backend.
     - Vite builds ES-module `.js` outputs; the backend renders `<script
       type="module">` for them (module scripts defer by default).
diff --git a/frontend/src/StructureEditor.vue b/frontend/src/StructureEditor.vue
index 50f2fe3..5f71491 100644
--- a/frontend/src/StructureEditor.vue
+++ b/frontend/src/StructureEditor.vue
@@ -228,23 +228,7 @@ async function commitSlug(node, ev) {
   }
 }
 
-// Two-step delete (no dialogs): the first click arms the row's button for
-// a few seconds, the second actually deletes.
-const arming = ref(null)
-let armTimer = null
-
-function armRemove(node) {
-  if (arming.value === node.path) {
-    clearTimeout(armTimer)
-    arming.value = null
-    removePage(node)
-  } else {
-    arming.value = node.path
-    clearTimeout(armTimer)
-    armTimer = setTimeout(() => { arming.value = null }, 3000)
-  }
-}
-
+// Deletion is immediate, no confirmation.
 async function removePage(node) {
   const res = await fetch(`/_api/pages/${node.path}`, { method: 'DELETE' })
   if (res.ok) {
@@ -267,8 +251,7 @@ async function removePage(node) {
 provide('structureHandlers', {
   current: () => path.value,
   open: navigate,
-  arming: () => arming.value,
-  armRemove,
+  removePage,
   reorder: onReorder,
   titleInput: onTitleInput,
   commitSlug,
@@ -284,7 +267,6 @@ onMounted(() => {
 })
 
 onUnmounted(() => {
-  clearTimeout(armTimer)
   for (const t of Object.values(timers)) clearTimeout(t)
   removeEventListener('pagerite:editor-shown', onEditorShown)
 })
diff --git a/frontend/src/StructureTree.vue b/frontend/src/StructureTree.vue
index 67e281c..b8cf74c 100644
--- a/frontend/src/StructureTree.vue
+++ b/frontend/src/StructureTree.vue
@@ -144,12 +144,11 @@ function onEnd() {
                 v-if="element.has_content || !element.children.length"
                 type="button"
                 class="act del"
-                :class="{ armed: handlers.arming() === element.path }"
                 :title="element.children.length
                   ? 'delete the landing page (the category keeps its subpages)'
                   : 'delete page'"
-                @click="handlers.armRemove(element)"
-              >{{ handlers.arming() === element.path ? 'delete?' : '✕' }}</button>
+                @click="handlers.removePage(element)"
+              >✕</button>
             </span>
           </template>
         </div>
@@ -300,12 +299,6 @@ body.tree-dragging .treelist {
   white-space: nowrap;
 }
 
-/* Two-step delete: the first click arms the button, the second deletes. */
-.act.armed {
-  color: #e06c75;
-  font-weight: 600;
-}
-
 .del:hover {
   color: #e06c75;
 }
diff --git a/frontend/src/assets/pagerite.css b/frontend/src/assets/pagerite.css
index 97ff90d..385937e 100644
--- a/frontend/src/assets/pagerite.css
+++ b/frontend/src/assets/pagerite.css
@@ -132,22 +132,35 @@ body {
   overflow: hidden;
   /* Stack the design artwork and the page's own banner code on top of
      each other (artwork first): the banner is a background layer, author
-     code overlays it. A single child behaves exactly as before. */
+     code overlays it. A single child behaves exactly as before. The track
+     is explicitly banner-sized: an auto row would size to the content
+     (an SVG's intrinsic aspect ratio makes it far taller than the banner),
+     and children's height:100% would resolve against that bloated row. */
   display: grid;
+  grid-template: 100% / 100%;
 }
 
 /* :not(style, script): author-level display:block would override the UA's
-   display:none on those and render their source as banner text. */
+   display:none on those and render their source as banner text. No
+   width/height: the default stretch alignment fills the track without a
+   percentage-resolution cycle. */
 #page-banner>*:not(style, script) {
   grid-area: 1 / 1;
   display: block;
-  width: 100%;
-  height: 100%;
   object-fit: cover;
+  /* Banner artwork is bottom-anchored: the meaningful content (horizon,
+     ground, characters) sits at the bottom, so on wide viewports — where
+     the fixed-height banner crops the artwork vertically — the sky/top is
+     what scrolls out of view. object-position covers replaced elements
+     (img, canvas); inline SVG is anchored by the transform-origin below
+     together with preserveAspectRatio="...YMax slice" in the artwork. */
+  object-position: bottom;
   /* Scroll parallax: pagerite.js sets --pry on <html>; the banner stays
      windowed in place while the artwork drifts inside it. The scale
-     provides overscan so the drift never reveals an edge. */
+     provides overscan so the drift never reveals an edge; scaling from the
+     bottom keeps the artwork's bottom edge pinned to the banner's. */
   transform: scale(1.25) translateY(var(--pry, 0px));
+  transform-origin: bottom;
   will-change: transform;
 }
 
diff --git a/frontend/src/pagerite.js b/frontend/src/pagerite.js
index 0991f91..1df2815 100644
--- a/frontend/src/pagerite.js
+++ b/frontend/src/pagerite.js
@@ -268,29 +268,31 @@ import "overlayscrollbars/overlayscrollbars.css";
     }
   }
 
-  // --- Preloading ------------------------------------------------------
-  // Warm the HTTP cache with all linked pages and their resources, so
-  // navigation (and the cube transition) is instant. Pages carry ETags,
-  // so re-running this after each navigation revalidates cheaply (304)
-  // and picks up changed content and images.
+  // --- Page cache / preloading ------------------------------------------
+  // Articles are deliberately NOT HTTP-cacheable, so speed comes from an
+  // in-memory cache instead: at load (and after each swap) every visible
+  // internal link is fetched exactly once, and navigation is served from
+  // memory with no fetch at all. Editor re-renders (swapdoc.loadPlain)
+  // announce their fresh copies via pagerite:page-fetched, keeping the
+  // cache in sync after edits.
+  const pageCache = new Map(); // pathname -> HTML text
+  addEventListener("pagerite:page-fetched", (ev) => {
+    pageCache.set(new URL(ev.detail.url, location.href).pathname, ev.detail.html);
+  });
+
   function preload() {
-    const urls = new Set();
-    for (const a of document.querySelectorAll('#nav a[href^="/"], #main a[href^="/"]')) {
+    const urls = new Set([location.pathname]);
+    for (const a of document.querySelectorAll(
+      '#nav a[href^="/"], #sidebar a[href^="/"], #main a[href^="/"]',
+    )) {
       urls.add(a.pathname);
     }
     for (const url of urls) {
-      if (url === location.pathname) continue;
+      if (pageCache.has(url)) continue;
       fetch(url)
-        .then((r) => (r.ok ? r.text() : ""))
-        .then((html) => {
-          if (!html) return;
-          // Off-screen parse: load the page's images and other resources
-          const doc = new DOMParser().parseFromString(html, "text/html");
-          for (const img of doc.querySelectorAll("img")) {
-            const i = new Image();
-            i.src = img.src;
-          }
-        })
+        .then((r) => (r.ok && (r.headers.get("content-type") || "").includes("text/html")
+          ? r.text() : ""))
+        .then((html) => { if (html) pageCache.set(url, html); })
         .catch(() => {});
     }
   }
@@ -333,16 +335,21 @@ import "overlayscrollbars/overlayscrollbars.css";
     }
     let doc;
     let finalUrl = url;
-    try {
-      const res = await fetch(url);
-      const type = res.headers.get("content-type") || "";
-      if (!res.ok || !type.includes("text/html")) throw new Error("not a page");
-      // Reflect any redirect the server issued.
-      if (res.redirected) finalUrl = res.url;
-      doc = new DOMParser().parseFromString(await res.text(), "text/html");
-    } catch {
-      location.href = url; // fall back to a normal navigation
-      return;
+    const cached = pageCache.get(new URL(url, location.href).pathname);
+    if (cached) {
+      doc = new DOMParser().parseFromString(cached, "text/html");
+    } else {
+      try {
+        const res = await fetch(url);
+        const type = res.headers.get("content-type") || "";
+        if (!res.ok || !type.includes("text/html")) throw new Error("not a page");
+        // Reflect any redirect the server issued.
+        if (res.redirected) finalUrl = res.url;
+        doc = new DOMParser().parseFromString(await res.text(), "text/html");
+      } catch {
+        location.href = url; // fall back to a normal navigation
+        return;
+      }
     }
     if (REGIONS.some((id) => !doc.getElementById(id))) {
       location.href = url;
diff --git a/frontend/src/swapdoc.js b/frontend/src/swapdoc.js
index 51f7326..aaffaf0 100644
--- a/frontend/src/swapdoc.js
+++ b/frontend/src/swapdoc.js
@@ -100,18 +100,22 @@ function swapRegions(doc) {
 export async function loadPlain(p) {
   let doc
   let finalUrl = `/${p}`
+  let html
   try {
     const res = await fetch(finalUrl)
     const type = res.headers.get('content-type') || ''
     if (!type.includes('text/html')) return null
     if (res.redirected) finalUrl = res.url
-    doc = new DOMParser().parseFromString(await res.text(), 'text/html')
+    html = await res.text()
+    doc = new DOMParser().parseFromString(html, 'text/html')
   } catch { return null }
   if (!doc.getElementById('main')) return null
   swapRegions(doc)
   history.replaceState(null, '', finalUrl)
   runScripts(document.getElementById('page-banner'))
   runScripts(document.getElementById('main'))
+  // Keep pagerite.js's in-memory page cache in sync with the fresh copy.
+  dispatchEvent(new CustomEvent('pagerite:page-fetched', { detail: { url: finalUrl, html } }))
   dispatchEvent(new CustomEvent('pagerite:preview')) // re-inject + re-tuck the edit pens
   return finalUrl
 }
diff --git a/pagerite/app.py b/pagerite/app.py
index b5bcc33..3f9bd2a 100644
--- a/pagerite/app.py
+++ b/pagerite/app.py
@@ -686,11 +686,12 @@ async def show_page(request: Request, path: str) -> HTMLResponse | Response:
     chain = resolve(data.menu, path)
     node = chain[-1] if chain else None
     if node is not None and node.published and node.content is not None:
-        # ETag on content + render version; clients revalidate cheaply,
-        # which keeps prefetched pages warm and current. no-cache forces
-        # that revalidation: with Last-Modified but no Cache-Control,
-        # browsers would otherwise cache heuristically and serve stale
-        # pages (e.g. after a theme change) without asking us at all.
+        # no-cache forbids serving a stored page without revalidation
+        # (browsers would otherwise cache heuristically and serve stale
+        # pages, e.g. after a theme change). In-session speed instead comes
+        # from pagerite.js's in-memory page cache (preload everything, never
+        # fetch on navigation); the ETag just makes those one-time preload
+        # fetches and any revalidation cheap.
         etag = f'"{path}@{node.modified.timestamp()}v{data.version}"'
         if request.headers.get("if-none-match") == etag:
             return Response(status_code=304)
diff --git a/pagerite/seed.py b/pagerite/seed.py
index 41a9ded..6333d5f 100644
--- a/pagerite/seed.py
+++ b/pagerite/seed.py
@@ -1,147 +1,275 @@
-"""Seed content written to the database on first run (when it is empty).
+"""Seed content written to the database on first creation only
+(``@kanta.bootstrap`` in ``app.py``).
 
-Demonstrates the formatting options: images attached to pages and served
-from the page path, figures with captions, attribute classes for
-positioning, footnotes, definition lists, task lists, tables and raw HTML.
+A "welcome to your new site" starter: a structured docs section (three
+menu levels deep) covering editing and the full Markdown feature set —
+each feature shown as its Markdown source in a code block followed by
+the rendered result — and a showcase section with image positioning,
+long-form layout and a simple custom banner.
 """
 
 WELCOME = """\
-Welcome to your new **Pagerite** site. Pages are written in Markdown — including raw HTML — and served from pretty URLs.
+Welcome to your new **Pagerite** site. Everything you see is a page written in Markdown, served from a pretty URL, and editable right here in the browser.
 
-Have a look around:
+Where to go next:
 
-- The [docs](/docs) section explains [how to write content](/docs/editing), including images and positioning.
-- [The Long Read](/blog/the-long-read) demonstrates a longer article with scroll effects.
-- The [about](/about) page shows off assorted formatting.
+- The [docs](/docs/editing) section explains how to edit this site and shows every supported Markdown feature, source and result side by side.
+- The [showcase](/showcase/gallery) section shows what finished pages can look like: image positioning, banners, a long read.
+- Click the 🖊️ pen on any page to open the editor, and the ⚙️ pen for site settings and the structure tree.
 
 ![Abstract waves](waves.svg "Generated SVG artwork, attached to this page")
+
+*Delete or rewrite any of these pages — they are only here to get you started.*
 """
 
-ABOUT = """\
-This site runs on **Pagerite**: FastAPI + html5tagger + kanta, with content written in Markdown.
+EDITING = """\
+Everything on the site is editable in place. Log in, and pens appear: 🖊️ on the page and banner, ⚙️ in the banner corner for site settings.
 
-Some formatting samples:
+## The editor
 
-- [x] Write content in Markdown
-- [x] Attach images to pages
-- [ ] Add editing UI
+The 🖊️ pens open a tabbed editor over the page you are viewing:
 
-Term
-: A definition list entry, rendered by the deflist plugin.
+- **Article** — the page's title and Markdown, with a live preview. The format bar inserts the harder-to-remember syntax (links, tables, images); Ctrl/Cmd-B, I and S do what you expect. Saving is explicit: 💾 or Ctrl+S.
+- **Banner** — per-page banner HTML and a banner design picker. Banners are raw HTML (an image, a styled div, a canvas with a script) and subpages inherit the nearest banner up their path.
+- **Site** — brand, theme, fonts, favicon and custom CSS, all applied immediately.
+- **Structure** — the page tree. Drag rows to reorder or nest, rename titles and slugs inline, ➕ adds a page, ✕ deletes one.
 
-And a table:
+## URLs and structure
+
+The URL is the structure: a page at `docs/markdown/basics` lives under `docs` and `markdown`, and the menus are derived from that. Slugs are lowercase ASCII (`a-z 0-9 - _`). A node without content is a category label — it renders a placeholder and its menu link points at its first child page.
+
+Images and files uploaded anywhere land in a content-addressed store served from `/_f/{hash}.ext`, so links survive page moves. The article editor's format bar and copy-paste both upload images for you.
+
+{dates}
+"""
+
+MD_BASICS = """\
+Every feature below is shown twice: first the Markdown source, then how it renders.
+
+## Headings and text
+
+```markdown
+## A section heading
+### A subsection
+
+*Emphasis*, **strong**, ~~strikethrough~~, `inline code`, and a
+[link to the front page](/). Plain URLs become links automatically:
+https://example.com — and a hard line break
+is just a newline.
+```
+
+## A section heading
+### A subsection
+
+*Emphasis*, **strong**, ~~strikethrough~~, `inline code`, and a [link to the front page](/). Plain URLs become links automatically: https://example.com — and a hard line break
+is just a newline.
+
+## Lists and quotes
+
+```markdown
+- One
+- Two
+  - Nested
+
+1. First
+2. Second
+
+> A blockquote. The URL space is the author's:
+> pretty slugs at the root, nesting only where
+> the content is genuinely structured.
+```
+
+- One
+- Two
+  - Nested
+
+1. First
+2. Second
+
+> A blockquote. The URL space is the author's:
+> pretty slugs at the root, nesting only where
+> the content is genuinely structured.
+
+## Code
+
+Fenced blocks get server-side syntax highlighting:
+
+````markdown
+```python
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+```
+````
+
+```python
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+```
+
+## Tables
+
+```markdown
+| Feature | Status |
+|---------|--------|
+| Pages   | done   |
+| Images  | done   |
+```
 
 | Feature | Status |
 |---------|--------|
 | Pages   | done   |
 | Images  | done   |
-| Comments| later  |
+"""
 
-Footnotes work too.[^1]
+MD_EXTENSIONS = """\
+Markdown extensions enabled on this site, source first, then rendered.
+
+## Footnotes
+
+```markdown
+Footnotes work inline.[^1]
 
 [^1]: Rendered at the bottom of the page, with a back-reference.
+```
+
+Footnotes work inline.[^1]
+
+[^1]: Rendered at the bottom of the page, with a back-reference.
+
+## Definition lists
+
+```markdown
+Term
+: A definition list entry.
+
+Another term
+: With its definition.
+```
+
+Term
+: A definition list entry.
+
+Another term
+: With its definition.
+
+## Task lists
+
+```markdown
+- [x] Write content in Markdown
+- [x] Attach images to pages
+- [x] Make tasks clickable on the rendered page
+```
+
+- [x] Write content in Markdown
+- [x] Attach images to pages
+- [x] Make tasks clickable on the rendered page
+
+## Admonitions
+
+```markdown
+!!! note
+    An admonition block for notes, warnings, tips...
+```
+
+!!! note
+    An admonition block for notes, warnings, tips...
+
+## Sub- and superscript
+
+```markdown
+H~2~O and x^2^ + y^2^ = z^2^.
+```
+
+H~2~O and x^2^ + y^2^ = z^2^.
+
+## Raw HTML
+
+HTML passes through untouched — useful for `<kbd>` keys, `<details>` sections, embedded media:
+
+```html
+<details><summary>Click to expand</summary>Hidden content.</details>
+```
+
+<details><summary>Click to expand</summary>Hidden content.</details>
+
+## Smart typography
+
+The typographer is on, so straight quotes become curly, `--` becomes -- and `...` becomes ...
 """
 
-EDITING = """\
-Pages are written in Markdown with extensions. Everything below is plain Markdown source — no special support from the article is needed for the site's layout or scroll effects.
+MD_LAYOUT = """\
+## Images and figures
 
-## Images
+An image standing alone in its paragraph becomes a `<figure>`; its title becomes the caption. Inline images within text stay plain.
 
-Upload a file (`PUT /_api/files/{filename}`) and it lands in the content-addressed store, served immutable from `/_f/{hash}.ext` — an absolute URL that survives page moves:
-
-```
-![Abstract shapes](/_f/....svg "A captioned figure"){.right width=280}
+```markdown
+![Abstract shapes](shapes.svg "A captioned figure")
 ```
 
-![Abstract shapes](shapes.svg "A captioned figure, floated right with an attribute class"){.right width=280}
+![Abstract shapes](shapes.svg "A captioned figure")
 
-The title becomes a `<figcaption>`, and brace attributes (the attrs plugin) control positioning: `{.right}`, `{.left}`, `{.wide}`, plus plain attributes like `width=280`. Absolute and external URLs pass through unchanged.
+## Positioning with attributes
 
-## Text
+Brace attributes (the attrs plugin) control placement: `{.right}` and `{.left}` float, `{.wide}` breaks out of the text column, and plain attributes like `width=280` pass through.
 
-*Emphasis*, **strong**, ~~strikethrough~~, `inline code`, and [links](/about) as usual. Blockquotes:
-
-> The URL space is the author's. Pretty slugs at the root, nesting only
-> where the content is genuinely structured.
-
-## Code
-
-```python
-def render(text: str, page_path: str) -> str:
-    return md.render(text, {"page_path": page_path})
+```markdown
+![Abstract shapes](shapes.svg "Floated right"){.right width=280}
 ```
-"""
 
-LONG_READ = """\
-*An essay long enough to scroll, to demonstrate the gentle reveal of headings, figures and code blocks as they enter the viewport.*
+![Abstract shapes](shapes.svg "Floated right — text wraps around it"){.right width=280}
+
+Floated images let the text wrap around them, like this paragraph does. Relative image paths resolve against the page's own path, so attached files travel with the page. Uploaded files get content-addressed `/_f/` URLs that never break, no matter where the page moves.
+
+{.wide} artwork spans the full content width:
+
+```markdown
+![Dunes](dunes.svg "Full-width artwork"){.wide}
+```
+
+![Dunes](dunes.svg "Full-width artwork between sections"){.wide}
+
+## Datelines
+
+A `{dates}` line on its own expands to the article's published/updated dateline:
+
+```markdown
+{dates}
+```
 
 {dates}
 
-![Layered dunes](dunes.svg "Full-width artwork between sections"){.wide}
+## The page title
 
-## Chapter one
-
-The distinction between a blog and a website is largely an accident of history. Early content management systems filed everything under "posts", stamped them with a date, and arranged them in reverse chronological order under a `/blog/` prefix. Anything else was a "page", which lived somewhere else entirely, often in a separate editing interface with separate rules.
-
-But readers do not think in these terms. A reader follows a link, reads what is there, and follows another link. The URL is a promise about where something lives, not about which database table it came from. Pagerite therefore treats every piece of content as a page: named, addressable, and rendered on the fly.
-
-## Chapter two
-
-Consider what happens to URLs when the tooling leads the design. You get addresses like `/cms/frontpage` or `/blog/post1` — the name of the machine leaking into the name of the thing. The slug should be chosen by the author, the way a book's title is chosen, and it should sit at the root of the site like the title sits on the cover.
-
-Nesting still has its place. Structured content — documentation, a series, a portfolio — benefits from paths that mirror the structure. The navigation on this very site is derived from the paths: open a section, and you see what it contains. No menu editor, no duplication of structure in two places.
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
-
-Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt.
-
-## Chapter three
-
-On the reading experience itself: motion on the web is usually either absent or obnoxious. The interesting middle ground is motion that acknowledges the reader's own movement — the scroll. Elements that fade in as they enter the viewport give the page a sense of depth, as if the content were arriving just in time.
-
-Crucially, none of this may depend on the article. The author writes Markdown; the effects come from the layout. And when the reader prefers reduced motion, everything must hold still.
-
-Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur?
-
-```text
-Quis autem vel eum iure reprehenderit
-qui in ea voluptate velit esse quam nihil
-molestiae consequatur, vel illum qui
-dolorem eum fugiat quo voluptas nulla pariatur?
-```
-
-At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis praesentium voluptatum deleniti atque corrupti quos dolores et quas molestias excepturi sint occaecati cupiditate non provident, similique sunt in culpa qui officia deserunt mollitia animi, id est laborum et dolorum fuga. Et harum quidem rerum facilis est et expedita distinctio.
-
-## Chapter four
-
-Nam libero tempore, cum soluta nobis est eligendi optio cumque nihil impedit quo minus id quod maxime placeat facere possimus, omnis voluptas assumenda est, omnis dolor repellendus. Temporibus autem quibusdam et aut officiis debitis aut rerum necessitatibus saepe eveniet ut et voluptates repudiandae sint et molestiae non recusandae.
-
-Itaque earum rerum hic tenetur a sapiente delectus, ut aut reiciendis voluptatibus maiores alias consequatur aut perferendis doloribus asperiores repellat. And so we arrive back where we started: the blog and the website were one thing all along. [Return to the front page](/).
+If your Markdown contains its own `# heading`, the page title is not repeated as a second h1 — it still supplies the `<title>` and the menu labels.
 """
 
-NOTES_ON_URLS = """\
-A URL is part of the content. A few rules of thumb I keep coming back to:
+GALLERY = """\
+Pages can attach images and position them freely. All artwork here is generated SVG, stored content-addressed and served from `/_f/`.
 
-- Pick slugs like book titles, not like database keys.
-- Nest only when the structure is real.
-- Once published, a URL is a promise. Redirect if you must break it.
+![Shapes](shapes.svg "Floated left with {.left}"){.left width=240}
 
-> Cool URIs don't change; uncool ones at least apologise.
+This text wraps around a left-floated figure. The caption comes from the image title, the float from `{.left width=240}` — brace attributes on the image itself.
 
-That's all. Short posts are posts too.
+![Waves](waves.svg "Floated right with {.right}"){.right width=240}
+
+Mixing floats in one article is fine. Both images were uploaded to this page and referenced by relative path, so the whole page (images included) can be moved in the structure tree without breaking anything.
+
+![Dunes](dunes.svg "Full-bleed with {.wide}"){.wide}
+
+A wide image escapes the text column for emphasis between sections. No HTML needed — just Markdown and an attribute.
 """
 
-CANVAS_NIGHTS = """\
-This post's banner is not an image at all — it's a `<canvas>` animated by a few lines of JavaScript embedded in the page's banner HTML.
+NIGHT_SKY = """\
+This page's banner is not an image — it's a few lines of HTML stored with the page:
 
-Banners on this site are arbitrary markup: an image, a gradient div, or a small animated scene like the one above. Subpages inherit the nearest banner up their path, so a whole section can share one look.
-
-```js
-// the essence of the banner above
-stars.forEach(s => { s.x = (s.x + s.speed * dt) % 1 })
+```html
+<div style="background: linear-gradient(100deg, #14243d, #3d2b6b 45%,
+     #7c5cff 75%, #ff5c8a); height: 100%"></div>
 ```
 
-No build step, no framework — the snippet is stored with the page and dropped into the header as-is.
+Banners are arbitrary trusted markup: a styled div, an `<img>`, even a canvas with a script. Subpages inherit the nearest banner up their path, so a whole section can share one look — this one is set on a leaf page, so nothing else inherits it.
+
+For animated banners, pick a **banner design** in the banner editor instead of writing code: this site ships `stars` (a drifting starfield) and `eyes` (a critter in the grass), and themes can bring their own. Designs are folders in `pagerite/themes/{name}/` — a `banner.css` plus a `banner.html` or `banner.svg` — and are selectable on any page via the UI.
 """
 
 SMALL_RELEASES = """\
@@ -154,39 +282,20 @@ Software wants to be shipped. The longer a change sits unmerged, the more it rot
 A release is a conversation with reality. Small releases keep the conversation lively.
 """
 
-CANVAS_BANNER = """\
-<canvas id="stars"></canvas>
-<script>
-(() => {
-  const c = document.getElementById("stars");
-  const ctx = c.getContext("2d");
-  const fit = () => { c.width = c.clientWidth; c.height = c.clientHeight; };
-  fit();
-  addEventListener("resize", fit);
-  const stars = Array.from({ length: 110 }, () => ({
-    x: Math.random(), y: Math.random(),
-    r: Math.random() * 1.4 + 0.3, v: Math.random() * 0.05 + 0.01,
-  }));
-  let prev = performance.now();
-  (function frame(now) {
-    if (!c.isConnected) return;
-    const dt = Math.min(now - prev, 100); prev = now;
-    ctx.fillStyle = "#0b0e1d";
-    ctx.fillRect(0, 0, c.width, c.height);
-    ctx.fillStyle = "#cdd6ff";
-    for (const s of stars) {
-      s.x = (s.x + s.v * dt / 1000) % 1;
-      ctx.beginPath();
-      ctx.arc(s.x * c.width, s.y * c.height, s.r, 0, 7);
-      ctx.fill();
-    }
-    requestAnimationFrame(frame);
-  })(prev);
-})();
-</script>
+ABOUT = """\
+This site runs on **Pagerite**: FastAPI + html5tagger + kanta, with content written in Markdown and rendered on the fly.
+
+- [How to edit this site](/docs/editing)
+- [Markdown features](/docs/markdown/basics)
+- [The showcase](/showcase/gallery)
+
+*Replace this page with whatever your site is about.*
 """
 
-BLOG_BANNER = '<div style="background: linear-gradient(100deg, #14243d, #3d2b6b 45%, #7c5cff 75%, #ff5c8a)"></div>'
+BANNER_DIV = (
+    '<div style="background: linear-gradient(100deg, #14243d, #3d2b6b 45%,'
+    ' #7c5cff 75%, #ff5c8a); height: 100%"></div>'
+)
 
 WAVES_SVG = """\
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 400">
@@ -231,33 +340,45 @@ DUNES_SVG = """\
 """
 
 #: path -> (title, markdown, {filename: bytes}, banner HTML, menu order,
-#: banner design). Banners are deliberately set only on select sub pages
-#: (not the front page), so the theme's default design shows elsewhere.
-#: Note there are deliberately no "docs" or "blog" landing pages: those
-#: labels are created without content, so they render a placeholder page
-#: and their nav links point at the first child (see views.first_leaf).
+#: banner design). Banners are deliberately set only on one leaf page
+#: (showcase/night-sky), so nothing else inherits a custom banner.
+#: Note there are deliberately no "docs" or "showcase" landing pages:
+#: those labels are created without content, so they render a placeholder
+#: page and their nav links point at the first child (see
+#: views.first_leaf).
 PAGES: dict[str, tuple[str, str, dict[str, bytes], str, float, str | None]] = {
     "": ("Welcome", WELCOME, {"waves.svg": WAVES_SVG.encode()}, "", 1, None),
-    "about": ("About", ABOUT, {}, "", 2, None),
-    "docs/editing": (
-        "Writing Content",
-        EDITING,
-        {"shapes.svg": SHAPES_SVG.encode()},
+    "about": ("About", ABOUT, {}, "", 3, None),
+    "docs/editing": ("Editing This Site", EDITING, {}, "", 1, None),
+    "docs/markdown/basics": (
+        "Markdown Basics",
+        MD_BASICS,
+        {},
         "",
         1,
         None,
     ),
-    "blog/the-long-read": (
-        "The Long Read",
-        LONG_READ,
-        {"dunes.svg": DUNES_SVG.encode()},
-        BLOG_BANNER,
+    "docs/markdown/extensions": ("Markdown Extensions", MD_EXTENSIONS, {}, "", 2, None),
+    "docs/markdown/images-and-layout": (
+        "Images and Layout",
+        MD_LAYOUT,
+        {"shapes.svg": SHAPES_SVG.encode(), "dunes.svg": DUNES_SVG.encode()},
+        "",
+        3,
+        None,
+    ),
+    "showcase/gallery": (
+        "Gallery",
+        GALLERY,
+        {
+            "shapes.svg": SHAPES_SVG.encode(),
+            "waves.svg": WAVES_SVG.encode(),
+            "dunes.svg": DUNES_SVG.encode(),
+        },
+        "",
         1,
         None,
     ),
-    # The eyes critter is a named banner design (pagerite/themes/eyes/),
-    # not code embedded in the page.
-    "blog/notes-on-urls": ("Notes on URLs", NOTES_ON_URLS, {}, "", 2, "eyes"),
-    "blog/canvas-nights": ("Canvas Nights", CANVAS_NIGHTS, {}, CANVAS_BANNER, 3, None),
-    "blog/small-releases": ("Small Releases", SMALL_RELEASES, {}, "", 4, None),
+    "showcase/night-sky": ("Night Sky", NIGHT_SKY, {}, BANNER_DIV, 2, None),
+    "showcase/small-releases": ("Small Releases", SMALL_RELEASES, {}, "", 3, None),
 }
diff --git a/pagerite/themes/corporate/banner.svg b/pagerite/themes/corporate/banner.svg
index 8cb3d41..7619ea4 100644
--- a/pagerite/themes/corporate/banner.svg
+++ b/pagerite/themes/corporate/banner.svg
@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 360" preserveAspectRatio="xMidYMid slice">
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 360" preserveAspectRatio="xMidYMax slice">
   <defs>
     <linearGradient id="cbg" x1="0" y1="0" x2="0" y2="1">
       <stop offset="0" class="cb-bg0"/>
diff --git a/pagerite/themes/nitro/banner.svg b/pagerite/themes/nitro/banner.svg
index c7052b5..7d485b5 100644
--- a/pagerite/themes/nitro/banner.svg
+++ b/pagerite/themes/nitro/banner.svg
@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 360" preserveAspectRatio="xMidYMid slice">
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 360" preserveAspectRatio="xMidYMax slice">
   <defs>
     <linearGradient id="flare" x1="0" y1="0" x2="1" y2="0">
       <stop offset="0" stop-color="#ff6a00"/>
diff --git a/pagerite/themes/purple/banner.svg b/pagerite/themes/purple/banner.svg
index 45814a3..cbb05ae 100644
--- a/pagerite/themes/purple/banner.svg
+++ b/pagerite/themes/purple/banner.svg
@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 300" preserveAspectRatio="xMidYMid slice">
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 300" preserveAspectRatio="xMidYMax slice">
   <defs>
     <linearGradient id="sky" x1="0" y1="0" x2="0" y2="1">
       <stop offset="0" stop-color="#2b1b4d"/>
diff --git a/pagerite/themes/stars/banner.css b/pagerite/themes/stars/banner.css
new file mode 100644
index 0000000..015a1ac
--- /dev/null
+++ b/pagerite/themes/stars/banner.css
@@ -0,0 +1,7 @@
+/* Stars banner design: a drifting starfield (banner.html — canvas + script
+   inlined by the backend into #page-banner). Fixed-height stage matching
+   the canvas. */
+
+#banner {
+  height: 240px;
+}
diff --git a/pagerite/themes/stars/banner.html b/pagerite/themes/stars/banner.html
new file mode 100644
index 0000000..8812a9c
--- /dev/null
+++ b/pagerite/themes/stars/banner.html
@@ -0,0 +1,52 @@
+<canvas id="stars"></canvas>
+<style>
+  #stars {
+    width: 100%;
+    height: 240px;
+    display: block;
+  }
+</style>
+<script><!--
+(() => {
+  const c = document.getElementById('stars')
+  const ctx = c.getContext('2d')
+  const DPR = devicePixelRatio || 1
+
+  const fit = () => {
+    const w = Math.max(1, c.clientWidth)
+    const h = Math.max(1, c.clientHeight)
+    c.width = Math.round(w * DPR)
+    c.height = Math.round(h * DPR)
+    ctx.setTransform(DPR, 0, 0, DPR, 0, 0)
+  }
+
+  fit()
+  addEventListener('resize', fit)
+
+  const stars = Array.from({ length: 110 }, () => ({
+    x: Math.random(),
+    y: Math.random(),
+    r: Math.random() * 1.4 + 0.3,
+    v: Math.random() * 0.05 + 0.01
+  }))
+
+  let prev = performance.now()
+  ;(function frame(now) {
+    if (!c.isConnected) return
+    const w = c.clientWidth
+    const h = c.clientHeight
+    const dt = Math.min(now - prev, 100)
+    prev = now
+    ctx.fillStyle = '#0b0e1d'
+    ctx.fillRect(0, 0, w, h)
+    ctx.fillStyle = '#cdd6ff'
+    for (const s of stars) {
+      s.x = (s.x + (s.v * dt) / 1000) % 1
+      ctx.beginPath()
+      ctx.arc(s.x * w, s.y * h, s.r, 0, 7)
+      ctx.fill()
+    }
+    requestAnimationFrame(frame)
+  })(prev)
+})()
+</script>
diff --git a/pagerite/themes/summer/banner.svg b/pagerite/themes/summer/banner.svg
index 21d1c95..9c45fe9 100644
--- a/pagerite/themes/summer/banner.svg
+++ b/pagerite/themes/summer/banner.svg
@@ -1,6 +1,6 @@
 <svg xmlns="http://www.w3.org/2000/svg"
      viewBox="0 0 1600 320"
-     preserveAspectRatio="xMidYMid slice">
+     preserveAspectRatio="xMidYMax slice">
 
   <defs>
     <linearGradient id="sky" x1="0" y1="0" x2="0" y2="1">