LeoVasanko
7f140001fa
Standalone markdown images (captioned or not) now become block <figure> elements; only inline-with-text images and raw author <img> HTML stay plain. This collapses the img/figure selector duplication in pagerite.css into a default + override structure: figure fills the column, floats go 30% (1em text gap), an explicit width attribute shrink-wraps the figure (images with width are left untouched by CSS so the attribute hint survives), and .wide re-anchors are grouped with the main rule.
254 lines
15 KiB
Markdown
254 lines
15 KiB
Markdown
# Pagerite Design Principles
|
||
|
||
Pagerite is a single-user CMS/blog. This document records the initial
|
||
high-level design decisions; it will be refined as the implementation
|
||
evolves.
|
||
|
||
## Architecture
|
||
|
||
- **Server-side rendered.** FastAPI serves complete HTML pages, generated in
|
||
Python with **html5tagger**. There is no client-side templating or SPA for
|
||
the public site.
|
||
- **Vue only where interactivity demands it.** Small interactive islands
|
||
(editing tools mainly) are Vue components mounted into specific elements of
|
||
the server-rendered pages. The public reading experience has no scripting
|
||
requirement.
|
||
- **Persistence via kanta.** Content is stored in an asyncio-friendly kanta
|
||
database. Rendering happens on the fly on each request — there are no
|
||
pre-built static artifacts.
|
||
|
||
## Content model
|
||
|
||
- Pages and blog articles are fundamentally the same kind of thing: named
|
||
pieces of content. The blog/website distinction is blurred; an article is
|
||
just a page (possibly with metadata such as a publication date and
|
||
listing in a feed).
|
||
- **Pretty URLs.** Content is addressed by its name (slug), not by technical
|
||
constructs — no `/cms/...` or `/blog/post1` prefixes. Slugs usually live
|
||
directly at the site root; structured content may nest
|
||
(`/docs/design-principles`-style). The URL space is the author's, so
|
||
reserved prefixes must be kept few and deliberate: everything internal
|
||
lives under `/_` (`/_api/`, `/_f/`, `/_assets/`). The only
|
||
other reserved root path is `/favicon.ico`, served from the build.
|
||
Slugs are lowercase ASCII letters, digits, hyphens and underscores
|
||
(`[a-z0-9_-]`; input is transliterated and filtered as you type, and a
|
||
new page's empty slug is derived from its title), may not begin with
|
||
`_` or `.`, and such URLs are never looked up as content.
|
||
- **Single user, trusted author.** No auth concerns in the core design.
|
||
Everything published is public; only editing tools will later sit behind
|
||
access control (external SSO when that time comes). The author is trusted
|
||
to create well-meaning slugs and content — no sanitization for safety,
|
||
only for correctness.
|
||
- **Commenting** is not planned now but the model should not preclude it
|
||
later.
|
||
|
||
## Authoring format
|
||
|
||
- Content is written in **Markdown** with powerful extensions (tables,
|
||
footnotes, code highlighting, etc.).
|
||
- **Embedded HTML is passed through unfiltered**, including inline scripts
|
||
and other dynamic content the author wants to post. This is safe by the
|
||
single-trusted-author assumption above.
|
||
- Renderer: **markdown-it-py** with mdit-py-plugins (footnotes, definition
|
||
lists, task lists, brace-attributes; tables and strikethrough from the
|
||
default preset), with `html=True` for raw passthrough,
|
||
`typographer=True` for SmartyPants-style replacements in body text (curly
|
||
quotes, `--` / `---` → en / em dashes, `...` → ellipsis, `(c)` → ©, etc.),
|
||
and `breaks=True` so single line breaks inside paragraphs become `<br>`.
|
||
Code spans/blocks and raw HTML are left untouched. Fenced code blocks are
|
||
highlighted server-side with
|
||
**Pygments** (`nowrap` spans styled by
|
||
`/_assets/pygments-*.css`, which maps every token class onto the `--code-*`
|
||
variables; the base stylesheet defines light and dark palette sets resolved
|
||
via `light-dark()`, so each theme gets the set matching its `color-scheme`
|
||
and may only retint `--code-bg` to keep the well in the page's color
|
||
family); a JS copy button appears on hover. Should this
|
||
prove limiting, we implement our own renderer on top of html5tagger,
|
||
which we already use for all HTML generation.
|
||
- **Files are content-addressed.** Uploads (`PUT /_api/files/{filename}`)
|
||
are stored by content hash — blake3, first 6 bytes hex + original
|
||
extension — and served immutable from `/_f/{hash}.ext`. Absolute URLs
|
||
that survive page renames and dedupe identical content; pages no longer
|
||
own files. An image standing alone in its paragraph becomes a block
|
||
`<figure>` — with `<figcaption>` when it has a title; images inline
|
||
with text and raw `<img>` HTML stay plain inline images. Positioning
|
||
is by attribute classes:
|
||
`{.right}` — `{.right}`, `{.left}` float at
|
||
30% of the text column (the caption wraps within it; an explicit
|
||
`width=300` makes the figure shrink-wrap the image instead),
|
||
`{.wide}` goes full bleed (viewport edge to edge, or up to the docked
|
||
editor; the sidebar stacks on top of it); plain attributes like `width=300`
|
||
work too. Headings (h1/h2) clear floats, so images never overflow into the
|
||
next section.
|
||
|
||
## Page structure and navigation
|
||
|
||
- 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.
|
||
- **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).
|
||
|
||
## Reading experience
|
||
|
||
- The article column is sized by the **viewport, never by content**: a
|
||
symmetric grid (`1fr minmax(0, 78rem) 1fr`) with flexible gutters keeps
|
||
the layout stable across navigation. The sidebar occupies the left
|
||
gutter, the right gutter balances it; wide screens get columns inside
|
||
long articles without changing the article's width.
|
||
- A gentle **scroll-reveal** of headings, figures and block-level elements
|
||
(IntersectionObserver). It is layout-level: articles need no support
|
||
for it, and `prefers-reduced-motion` disables all motion.
|
||
|
||
## Styling
|
||
|
||
- The base stylesheet `frontend/src/assets/pagerite.css` provides the layout,
|
||
typography and interaction rules with conservative CSS variables. A theme layer
|
||
(`pagerite/themes/{name}/theme.css` — currently `purple`, `corporate`
|
||
and `nitro`, served by the backend at `/_themes/{name}/theme.css` straight
|
||
from disk, never built) overrides those variables and
|
||
adds the visual styling; `Data.theme` selects the active theme (empty = none/base
|
||
only) and the site editor can switch it, choosing from the theme folders
|
||
found on disk. Vue may add per-component styles on top
|
||
where needed. The corporate and nitro themes switch palettes automatically via
|
||
`prefers-color-scheme` (corporate is light-first with a matching dark palette;
|
||
nitro a warm light-grey page or, in dark mode, a deep violet one — its dark
|
||
banner and orange accents carry over unchanged); purple (dusk) uses one
|
||
fixed palette for everyone. Themes may restyle structural details the base
|
||
leaves plain — heading colors and underlines, list markers, nav treatment,
|
||
brand sizing. A theme folder may also ship a **banner design**
|
||
(`banner.css` + `banner.svg`), selectable per page independently of the
|
||
active theme. The banner artwork has scroll parallax: pagerite.js sets the
|
||
`--pry` scroll parameter on `<html>` (event-driven, so it is still when the
|
||
page is idle), the banner contents drift within their window (with scale
|
||
overscan so no edge shows), and designs may key their own effects off the
|
||
same parameter — purple's sun rises as you scroll.
|
||
- Fonts, the shared stylesheet and pygments styles
|
||
live under `frontend/src/assets/` and are emitted as hashed assets under
|
||
`/_assets/`
|
||
(Source Serif 4 for headings, Source Sans 3 for body, Fira Code for code
|
||
by default; Fraunces, Literata, Cormorant, Playfair Display, Inter,
|
||
Montserrat, Cause, Exo 2 and New Rocker kept as woff2 options with
|
||
local `@font-face`, variable-weight where available). No third-party
|
||
requests.
|
||
|
||
## Editing
|
||
|
||
- Editing happens **in place**, in two modes opened by two pens:
|
||
- **Page mode** — the 🖊️ next to a page's heading (including 404s, which
|
||
is how new pages start) opens a CodeMirror Markdown editor docked to
|
||
the left of the article: the host sits inside `#content` (below the
|
||
banner, never over the footer), the content shifts right and the
|
||
sidebar hides while editing. Preview renders server-side per keystroke
|
||
(no debouncing) straight into the visible article's heading and body.
|
||
- **Site mode** — the 🖊️ on the banner opens a panel with the site
|
||
**brand** (applied to the header live), a **theme** selector (swapping
|
||
the theme stylesheet in place), **font** picks (heading/body/brand —
|
||
stored as plain `:root` rows inside the custom CSS, referencing the base
|
||
stylesheet's per-family font variables), a **site-wide custom CSS** field (injected
|
||
into `<style id="pagerite-user">` in the live page head and swapped during
|
||
fetch-navigation), the page's **banner design** selector (inherit /
|
||
none / any design found on disk, inherited by children), the page's
|
||
**banner HTML** field (supplementing the design, previewed into the
|
||
real banner region, so you see exactly which banner you're editing) and
|
||
the **structure tree**. Everything saves immediately as you edit — no
|
||
save button, no edit mode.
|
||
- Clicking a pen again closes the editor (without saving; a dirty preview
|
||
reloads the page). The pens are `<button>`s wired up by `pagerite.js` —
|
||
editing is an action, not a navigation. The editor's WebSocket
|
||
**reconnects automatically** with local text and pending saves preserved.
|
||
(All users are trusted authors for now; access control later with
|
||
SSO.)
|
||
- **CodeMirror 6** for Markdown editing (no WYSIWYG), title/published
|
||
controls.
|
||
Images can be pasted straight into the editor or chosen via a file
|
||
input: they upload to the content store (`PUT /_api/files/...`) and
|
||
insert `` at the cursor.
|
||
- The **structure panel** (vue-draggable tree of the whole site, in site
|
||
mode) covers page management: reorder any menu level, drag across
|
||
sections, add, delete (two clicks: the button arms, then deletes — no
|
||
dialogs). Every node is a real label — content-less category rows offer
|
||
a ➕ to give them a landing page.
|
||
Deleting a category removes only its landing page (the label and its
|
||
subpages stay). Every non-empty list ends with a ➕ row that starts a
|
||
new page as a local-only tree row at that level; the row can be dragged
|
||
into place before its title and slug are filled in and is persisted only
|
||
on commit. While dragging, these ➕ rows double as "end of this list"
|
||
drop targets; dropping ON the lower part of a row makes the page that
|
||
row's first child (even a leaf's, creating a sublist), while a row's
|
||
exposed top edge inserts a sibling before it. A dragged row's
|
||
indentation previews the target list's depth. Rows are always
|
||
editable: titles save while typing, slug edits commit on blur/Enter
|
||
since they rename the path (moving the whole subtree). The front page
|
||
is the root row with an empty slug — renaming it away leaves no front
|
||
page ("/" redirects to the first nav item), and giving another
|
||
top-level row the empty slug makes it the front page.
|
||
- Preview and saving go over a **WebSocket** (`/_api/ws/editor`) with a
|
||
stateless JSON protocol (`open`/`render`/`save`; on save all fields are
|
||
optional and absent ones keep their old values, `move_from` renames),
|
||
avoiding REST polling and races. Rendering always stays server-side.
|
||
- A REST API also exists for scripting, all under `/_api/`:
|
||
`GET pages` (the full tree), `PUT/DELETE pages/{path}`,
|
||
`GET/PUT settings` (site brand, theme and custom CSS), `POST structure`
|
||
(reorder/move/retitle), file upload/removal via `PUT/DELETE files/{name}`.
|
||
- On startup, seed pages from `pagerite/seed.py` are added **only if
|
||
missing** — existing user content is never overwritten.
|