diff --git a/pagerite/data.py b/pagerite/data.py
index 5de40a6..6ee699f 100644
--- a/pagerite/data.py
+++ b/pagerite/data.py
@@ -89,7 +89,7 @@ class Data(msgspec.Struct):
#: Active theme name (empty = none/base only). Themes live in
#: pagerite/themes/{theme}/ (theme.css and/or banner.css/banner.svg/
#: banner.html), served by the backend from disk.
- theme: str = "purple"
+ theme: str = "corporate"
#: Page transition design name (cube, crossfade, ...). Designs live in
#: pagerite/themes/{name}/transition.css and are injected as
#: #pagerite-transition on every page.
diff --git a/pagerite/seed-assets/md-chase.jpg b/pagerite/seed-assets/md-chase.jpg
deleted file mode 100644
index a33df25..0000000
Binary files a/pagerite/seed-assets/md-chase.jpg and /dev/null differ
diff --git a/pagerite/seed.py b/pagerite/seed.py
index c47fdee..fc90b28 100644
--- a/pagerite/seed.py
+++ b/pagerite/seed.py
@@ -2,10 +2,10 @@
(``@kanta.bootstrap`` in ``app.py``).
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.
+menu levels deep) covering editing and one long article that walks 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 banner designs.
Binary seed images live in ``seed-assets/`` (public domain, from
Wikimedia Commons: the two whale engravings are Augustus Burnham
@@ -26,10 +26,9 @@ Welcome to your new **Pagerite** site. Everything you see is a page written in M
Where to go next:
-- The [docs](/docs/editing) section explains how to edit this site and shows every supported Markdown feature, source and result side by side.
+- The [docs](/docs/editing) section explains how to edit this site and walks through 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.
-- Elsewhere on the web: [{width=240}](https://xkcd.com/927/) — a cautionary tale about adding one more standard.
{width=420}
@@ -50,37 +49,39 @@ The 🖊️ pens open a tabbed editor over the page you are viewing:
## 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.
+The URL is the structure: a page at `docs/markdown` lives under `docs`, 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. This site's own `docs` label demonstrates that, and the sidebar on this page shows the two submenu levels below it.
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 = """\
-# Markdown Basics
+# The full feature walkthrough: every supported extension in one long
+# article, each shown as Markdown source followed by the rendered result.
+MD_ARTICLE = """\
+# Markdown
-Every feature below is shown twice: first the Markdown source, then how it renders.
+Everything Pagerite's renderer supports, on one long page — each feature shown first as Markdown source, then rendered. This page is also the live demo of the reading layout: on a wide screen the text flows in columns, and side boxes lean into the margin.
-## Headings and text
+## Text and headings
```markdown
-## A section heading
-### A subsection
-
*Emphasis*, **strong**, ~~strikethrough~~, `inline code`, and a
-[link to the front page](/). An image that links to its page:
-[{width=240}](https://xkcd.com/1179/) — and a hard line break
+[link to the front page](/). A hard line break
is just a newline.
+
+Straight quotes become "curly", dashes -- and --- come out
+properly, and ... becomes an ellipsis, all automatically.
```
-## A section heading
-### A subsection
-
-*Emphasis*, **strong**, ~~strikethrough~~, `inline code`, and a [link to the front page](/). An image that links to its page: [{width=240}](https://xkcd.com/1179/) — and a hard line break
+*Emphasis*, **strong**, ~~strikethrough~~, `inline code`, and a [link to the front page](/). A hard line break
is just a newline.
-## Lists and quotes
+Straight quotes become "curly", dashes -- and --- come out properly, and ... becomes an ellipsis, all automatically.
+
+Headings from `##` down organize the article. On pages with at least three of them, each h1/h2 gets an anchor id and a self-link, so sections are linkable (try hovering a heading here) — and the editor's section pens and scroll sync key off the same anchors.
+
+## Lists
```markdown
- One
@@ -90,9 +91,9 @@ is just a newline.
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.
+- [x] Task lists with real checkboxes
+- [x] Clickable on the rendered page
+- [ ] Like this one
```
- One
@@ -102,13 +103,31 @@ is just a newline.
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.
+- [x] Task lists with real checkboxes
+- [x] Clickable on the rendered page
+- [ ] Like this one
+
+## Quotes and alerts
+
+```markdown
+> A blockquote. Newlines inside it are kept,
+> and a blank `>` line starts a new paragraph.
+
+> [!NOTE]
+> GitHub-style alerts — NOTE, TIP, IMPORTANT, WARNING, CAUTION —
+> render as callout boxes.
+```
+
+> A blockquote. Newlines inside it are kept,
+> and a blank `>` line starts a new paragraph.
+
+> [!NOTE]
+> GitHub-style alerts — NOTE, TIP, IMPORTANT, WARNING, CAUTION —
+> render as callout boxes.
## Code
-Fenced blocks get server-side syntax highlighting:
+Fenced blocks get server-side syntax highlighting, and a copy button on hover:
````markdown
```python
@@ -135,12 +154,6 @@ def greet(name: str) -> str:
|---------|--------|
| Pages | done |
| Images | done |
-"""
-
-MD_EXTENSIONS = """\
-# Markdown Extensions
-
-Markdown extensions enabled on this site, source first, then rendered.
## Footnotes
@@ -170,28 +183,6 @@ Term
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
@@ -200,6 +191,51 @@ H~2~O and x^2^ + y^2^ = z^2^.
H~2~O and x^2^ + y^2^ = z^2^.
+## Admonitions
+
+```markdown
+!!! note
+ An admonition block for notes, warnings, tips...
+
+!!! warning "Mind the whale"
+ With an optional custom title.
+```
+
+!!! note
+ An admonition block for notes, warnings, tips...
+
+!!! warning "Mind the whale"
+ With an optional custom title.
+
+## Containers and margin notes
+
+`::: name` wraps its contents in a `
` — brace attributes allowed. Three names are built in: `aside` floats a muted side box, `margin` marks a block as a margin note, and `nocols` opts its section out of the column layout. The `{.margin}` attribute does the same for a single block, written on its last line:
+
+````markdown
+::: aside
+A side box. On all but phone widths it floats in the side zone at
+the article's left, and the text never moves.
+:::
+
+This paragraph is a margin note.
+{.margin}
+
+::: nocols
+This section never flows into columns, however long the article.
+:::
+````
+
+::: aside
+A side box. On all but phone widths it floats in the side zone at the article's left, and the text never moves.
+:::
+
+This paragraph is a margin note.
+{.margin}
+
+::: nocols
+This section never flows into columns, however long the article.
+:::
+
## Raw HTML
HTML passes through untouched — useful for `` keys, `` sections, embedded media:
@@ -210,9 +246,23 @@ HTML passes through untouched — useful for `` keys, `` sections,
Click to expandHidden content.
-## Smart typography
+## Datelines
-The typographer is on, so straight quotes become curly, `--` becomes -- and `...` becomes ...
+A `{dates}` line on its own expands to the article's published/updated dateline:
+
+```markdown
+{dates}
+```
+
+{dates}
+
+## Images and layout
+
+An image standing alone in its paragraph becomes a ``; its title becomes the caption; brace attributes control placement — `{.right}`, `{.left}`, `{.margin}`, `{.wide}`, or plain ones like `width=280`. That deserves its own page: [Images and Layout](/docs/markdown/images-and-layout).
+
+## The page title
+
+If your Markdown contains its own `# heading`, the page title is not repeated as a second h1 — it still supplies the `` and the menu labels. This page is an example: its `# Markdown` heading *is* the title.
"""
MD_LAYOUT = """\
@@ -228,7 +278,7 @@ An image standing alone in its paragraph becomes a ``; its title becomes
## Positioning with attributes
-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.
+Brace attributes (the attrs plugin) control placement: `{.right}` and `{.left}` float, `{.margin}` moves a figure into the side zone, `{.wide}` breaks out of the text column, and plain attributes like `width=280` pass through.
```markdown
{.right width=280}
@@ -238,6 +288,14 @@ Brace attributes (the attrs plugin) control placement: `{.right}` and `{.left}`
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.
+```markdown
+{.margin}
+```
+
+{.margin}
+
+The same figure as a margin note: it leans into the side zone left of the text on all but phone widths, alongside the text it belongs to.
+
{.wide} artwork spans the full content width:
```markdown
@@ -245,64 +303,71 @@ Floated images let the text wrap around them, like this paragraph does. Relative
```
{.wide}
-
-## Datelines
-
-A `{dates}` line on its own expands to the article's published/updated dateline:
-
-```markdown
-{dates}
-```
-
-{dates}
-
-## The page title
-
-If your Markdown contains its own `# heading`, the page title is not repeated as a second h1 — it still supplies the `` and the menu labels.
"""
GALLERY = """\
-Pages can attach images and position them freely. The vector artwork here is generated SVG; the woodblock print is Hokusai's *The Great Wave off Kanagawa* (public domain, via Wikimedia Commons).
+This page's banner is the **eyes** design — a critter in the grass in — picked from banner menu (⚙️ in the top right corner). The selection applies to current page and all its children, allowing differently themed sections be created. [Night Sky](night-sky) picked its own. You should also find the theme settings, which allow choosing overall site theme, fonts and transitions. You may wish to try the more playful **summer** theme which the eyes theme builds on.
-{.wide}
+## Break out of the box!
-A wide image escapes the text column for emphasis between sections. No HTML needed — just Markdown and an attribute.
+{.wide}
-{.left width=240}
+::: aside
+
-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.
+## Aside boxes
-{.right width=240}
+When you have to sideline a bit with something important to say, use `::: aside` and end with `:::`, markdown between.
-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.
+On larger screens they break outside the normal page bounds. `{.margin}` can be used to a similar effect without a box.
+:::
+
+Images and text boxes can also be positioned for a more lively layout.
+
+{.right}
+
+This text wraps around a left or right floated figure. The caption comes from the image title, with additional styling like `{.left width=240}` — brace attributes on the image itself.
+
+Note how the layout may take different forms from a phone in portrait to widest of desktop browsers, not leaving large empty areas nor being constrained to a classic container box model.
+
+Lifting off elements here and there makes a great difference to how your site is received!
+
+### Design matters
+
+Good graphical design gives a website a clear visual structure and makes information easy to understand at a glance. Layout, spacing, typography, color, and imagery should work together to establish hierarchy and guide attention naturally through the page. Consistency between sections also helps users quickly learn how the interface is organized.
+
+A strong website layout balances visual character with usability. Content should have enough space to remain readable, while navigation and important actions should be easy to find without dominating the design. Responsive layouts should preserve these relationships across different screen sizes rather than simply shrinking the desktop arrangement.
"""
NIGHT_SKY = """\
This page's banner is not an image or a code snippet — it's the **stars** banner design, picked from a dropdown in the banner editor (🖊️ in the banner corner). Nothing is stored in the page beyond that choice.
-Banner designs are folders in `pagerite/themes/{name}/` — a `banner.css` plus a `banner.html` or `banner.svg` — so a design can be anything from a static gradient to an animated canvas like the starfield above. This site ships `stars` and `eyes` (a critter in the grass), and themes can bring their own.
+Banner designs are folders in `pagerite/themes/{name}/` — a `banner.css` plus a `banner.html` or `banner.svg` — so a design can be anything from a static gradient to an animated canvas like the starfield above. This site ships `stars` and `eyes` (a critter in the grass, seen on the [gallery](/showcase/gallery)), and themes can bring their own.
-Subpages inherit the nearest banner and design up their path, so a whole section can share one look. This page is a leaf: set a design here and nothing else is affected.
+Subpages inherit the nearest banner and design up their path, so a whole section can share one look — set one on a category and every page under it gets it, until a page overrides with its own. This page is a leaf: the design chosen here affects nothing else.
A page can also carry its own banner HTML — an ``, a styled div, a canvas with a script — which renders *on top of* the design's artwork, so author code always wins. But most of the time, picking a design is all you need.
"""
# Moby-Dick; or, The Whale (1851), Herman Melville — public domain.
# Chapter 1, abridged and headed. A real long-read: flowing sections,
-# figures, a list — not a feature showcase. (Engravings: Augustus
-# Burnham Shute's illustrations for the 1892 edition, public domain.)
+# figures, a list, side notes — not a feature showcase. (Engravings:
+# Augustus Burnham Shute's illustrations for the 1892 edition, public
+# domain; the wave is Hokusai, public domain.)
LOOMINGS = """\
*The opening of Herman Melville's Moby-Dick (1851), abridged — here to show what a longer article feels like: the multi-column layout on wide screens, images breaking up the text, and the gentle reveal as sections scroll into view.*
{dates}
-{.wide}
+{.wide}
## The watery part of the world
Call me Ishmael. Some years ago — never mind how long precisely — having little or no money in my purse, and nothing particular to interest me on shore, I thought I would sail about a little and see the watery part of the world. It is a way I have of driving off the spleen and regulating the circulation. Whenever I find myself growing grim about the mouth; whenever it is a damp, drizzly November in my soul; whenever I find myself involuntarily pausing before coffin warehouses, and bringing up the rear of every funeral I meet; and especially whenever my hypos get such an upper hand of me, that it requires a strong moral principle to prevent me from deliberately stepping into the street, and methodically knocking people's hats off — then, I account it high time to get to sea as soon as I can. This is my substitute for pistol and ball. With a philosophical flourish Cato throws himself upon his sword; I quietly take to the ship. There is nothing surprising in this. If they but knew it, almost all men in their degree, some time or other, cherish very nearly the same feelings towards the ocean with me.
-{.right width=320}
+::: aside
+Melville interrupts his story often — whole chapters on cetology, rope and chowder. Abridgments drop most of them, but notes like this one are where they would have gone.
+:::
There now is your insular city of the Manhattoes, belted round by wharves as Indian isles by coral reefs — commerce surrounds it with her surf. Right and left, the streets take you waterward. Its extreme downtown is the battery, where that noble mole is washed by waves, and cooled by breezes, which a few hours previous were out of sight of land. Look at the crowds of water-gazers there.
@@ -314,6 +379,9 @@ But look! here come more crowds, pacing straight for the water, and seemingly bo
Once more. Say you are in the country; in some high land of lakes. Take almost any path you please, and ten to one it carries you down in a dale, and leaves you there by a pool in the stream. There is magic in it. Let the most absent-minded of men be plunged in his deepest reveries — stand that man on his legs, set his feet a-going, and he will infallibly lead you to water, if water there be in all that region. Should you ever be athirst in the great American desert, try this experiment, if your caravan happen to be supplied with a metaphysical professor. Yes, as every one knows, meditation and water are wedded for ever.
+Ishmael sails from New Bedford, the whaling port south of Boston — Nantucket was the older, prouder whaling town, and he briefly considers it first.
+{.margin}
+
### The artist's problem
But here is an artist. He desires to paint you the dreamiest, shadiest, quietest, most enchanting bit of romantic landscape in all the valley of the Saco. What is the chief element he employs? There stand his trees, each with a hollow trunk, as if a hermit and a crucifix were within; and here sleeps his meadow, and there sleep his cattle; and up from yonder cottage goes a sleepy smoke. Deep into distant woodlands winds a mazy way, reaching to overlapping spurs of mountains bathed in their hill-side blue. But though the picture lies thus tranced, and though this pine-tree shakes down its sighs like leaves upon this shepherd's head, yet all were vain, unless the shepherd's eye were fixed upon the magic stream before him.
@@ -324,9 +392,9 @@ Why did the poor poet of Tennessee, upon suddenly receiving two handfuls of silv
Now, when I say that I am in the habit of going to sea whenever I begin to grow hazy about the eyes, and begin to be over conscious of my lungs, I do not mean to have it inferred that I ever go to sea as a passenger. For to go as a passenger you must needs have a purse, and a purse is but a rag unless you have something in it. Besides, passengers get sea-sick — grow quarrelsome — don't sleep of nights — do not enjoy themselves much, as a general thing; — no, I never go as a passenger; nor, though I am something of a salt, do I ever go to sea as a Commodore, or a Captain, or a Cook. I abandon the glory and distinction of such offices to those who like them. For my part, I abominate all honorable respectable toils, trials, and tribulations of every kind whatsoever. It is quite as much as I can do to take care of myself, without taking care of ships, barques, brigs, schooners, and what not.
-No, when I go to sea, I go as a simple sailor, right before the mast, plumb down into the forecastle, aloft there to the royal mast-head. True, they rather order me about some, and make me jump from spar to spar, like a grasshopper in a May meadow. And at first, this sort of thing is unpleasant enough. It touches one's sense of honor, particularly if you come of an old established family in the land, the Van Rensselaers, or Randolphs, or Hardicanutes. And more than all, if just previous to putting your hand into the tar-pot, you have been lording it as a country schoolmaster, making the tallest boys stand in awe of you. The transition is a keen one, I assure you, from a schoolmaster to a sailor, and requires a strong decoction of Seneca and the Stoics to enable you to grin and bear it. But even this wears off in time.
+{.right width=400}
-
+No, when I go to sea, I go as a simple sailor, right before the mast, plumb down into the forecastle, aloft there to the royal mast-head. True, they rather order me about some, and make me jump from spar to spar, like a grasshopper in a May meadow. And at first, this sort of thing is unpleasant enough. It touches one's sense of honor, particularly if you come of an old established family in the land, the Van Rensselaers, or Randolphs, or Hardicanutes. And more than all, if just previous to putting your hand into the tar-pot, you have been lording it as a country schoolmaster, making the tallest boys stand in awe of you. The transition is a keen one, I assure you, from a schoolmaster to a sailor, and requires a strong decoction of Seneca and the Stoics to enable you to grin and bear it. But even this wears off in time.
What of it, if some old hunks of a sea-captain orders me to get a broom and sweep down the decks? What does that indignity amount to, weighed, I mean, in the scales of the New Testament? Do you think the archangel Gabriel thinks anything the less of me, because I promptly and respectfully obey that old hunks in that particular instance? Who ain't a slave? Tell me that. Well, then, however the old sea-captains may order me about — however they may thump and punch me about, I have the satisfaction of knowing that it is all right; that everybody else is one way or other served in much the same way — either in a physical or metaphysical point of view, that is; and so the universal thump is passed round, and all hands should rub each other's shoulder-blades, and be content.
@@ -346,16 +414,19 @@ Software wants to be shipped. The longer a change sits unmerged, the more it rot
2. Ship it behind whatever door you like.
3. Let real use argue with your assumptions.
-A release is a conversation with reality. Small releases keep the conversation lively.
+A release is a conversation with reality. Small releases keep the conversation lively — and small *pieces* keep the whole thing standing, as [the comic on the About page](/about) illustrates all too well.
"""
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)
+- [Everything Markdown can do](/docs/markdown)
- [The showcase](/showcase/gallery)
-- [{width=240}](https://xkcd.com/2347/) — a small comic about small dependencies
+
+Pagerite keeps its dependency list short and knows every entry on it. Modern software in general builds on taller towers of other people's work:
+
+[{width=280}](https://xkcd.com/2347/)
*Replace this page with whatever your site is about.*
"""
@@ -403,56 +474,50 @@ DUNES_SVG = """\
"""
#: path -> (title, markdown, {filename: bytes}, banner HTML, menu order,
-#: banner design). Designs demonstrate inheritance: the "showcase" label
-#: picks "eyes" (all its pages show the critter), and the leaf
-#: "showcase/night-sky" overrides that with "stars". Elsewhere the active
-#: theme's own design shows.
+#: banner design). Designs demonstrate per-page choice: the gallery
+#: picks "eyes" (its page alone), night-sky picks "stars"; everything
+#: else inherits the active theme's own design.
#: 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). "showcase" is seeded explicitly (empty markdown,
-#: which the seeder leaves as content=None) just to carry the design.
+#: which the seeder leaves as content=None) purely to fix its menu order.
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, {}, "", 3, None),
"docs/editing": ("Editing This Site", EDITING, {}, "", 1, None),
- "docs/markdown/basics": (
- "Basics",
- MD_BASICS,
- {},
- "",
- 1,
- None,
- ),
- "docs/markdown/extensions": ("Extensions", MD_EXTENSIONS, {}, "", 2, None),
+ "docs/markdown": ("Markdown", MD_ARTICLE, {}, "", 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": ("Showcase", "", {}, "", 4, "eyes"),
- "showcase/gallery": (
- "Gallery",
- GALLERY,
{
- "great-wave.jpg": _asset("great-wave.jpg"),
"shapes.svg": SHAPES_SVG.encode(),
"waves.svg": WAVES_SVG.encode(),
+ "dunes.svg": DUNES_SVG.encode(),
},
"",
1,
None,
),
+ "showcase": ("Showcase", "", {}, "", 4, None),
+ "showcase/gallery": (
+ "Gallery",
+ GALLERY,
+ {
+ "dunes.svg": DUNES_SVG.encode(),
+ "shapes.svg": SHAPES_SVG.encode(),
+ "waves.svg": WAVES_SVG.encode(),
+ },
+ "",
+ 1,
+ "eyes",
+ ),
"showcase/loomings": (
"Loomings — a Long Read",
LOOMINGS,
{
- "dunes.svg": DUNES_SVG.encode(),
+ "great-wave.jpg": _asset("great-wave.jpg"),
"md-whale.jpg": _asset("md-whale.jpg"),
- "md-chase.jpg": _asset("md-chase.jpg"),
},
"",
2,