scavold 0.2.0-rc.3 → 0.2.0-rc.5

package/CHANGELOG.md

@@ -7,6 +7,94 @@ All notable changes to Scavold are documented here. The format follows
 While the version stays below `1.0.0` and carries a pre-release suffix, breaking
 changes may occur in any release.
 
+## [Unreleased]
+
+### Added
+
+- `:::pagelist` dates its entries the way the site wants them: `time-style` adds the
+  time of day, `timezone` names the zone the timestamps are read in, and both accept
+  `iso` alongside the `Intl` styles, writing `2020-10-20 12:16` in every language. The
+  default is unchanged — the date alone, read in UTC, which is where a front matter
+  value carrying no time of day belongs.
+- `formatTimestamp()` in `scavold/lib/dateFormat.js` renders timestamps the same way
+  for a theme's own components — a byline under a post's title, say. It is free of Vue
+  and VitePress and depends on its arguments alone, so pre-rendered markup and the
+  browser agree.
+
+### Changed
+
+- A `:::pagelist` that paginates reaches every page it found: `limit` now defaults to
+  `0` when `per-page` is set, rather than capping the selection at five entries and
+  leaving a pager to turn the pages of those five. A limit the author sets still wins.
+- Every link a site generates — menus, breadcrumbs, page lists, the feed, redirect targets
+  — names the file the page is built into: `/blog/post.html`, `/blog/index.html`,
+  `/index.html`. Links used to leave the extension off while VitePress's own markdown
+  links carried it, so one site spoke two dialects and the shorter one only worked on
+  servers that go looking for the file. Naming it is answered on the first attempt, and
+  the sitemap now lists the same URLs. The address bar still shows `/` and `/blog/`:
+  VitePress's router shortens them while navigating.
+
+### Fixed
+
+- The site's own `index.md` is no longer linked as `/index`, a URL no server has to
+  answer. The rule for a page's URL existed in three copies and now lives in
+  `lib/href.js` alone.
+- Scavold's built-in translations come from the bundle. They used to be fetched from a
+  URL that no build emits, so every page requested a file that was not there and the
+  interface silently fell back to English, whatever language the site is in.
+
+## [0.2.0-rc.4] — 2026-08-15
+
+### Added
+
+- `metaChunk` is on by default, keeping VitePress's page-hash map out of the inline
+  scripts. Its content changes with every build, so under a content security policy that
+  names script hashes it has to be updated on the server for every deploy — and when it
+  is not, the map is blocked and the client side of the site stops working while the
+  pre-rendered HTML still shows. What stays inline are VitePress's own two snippets,
+  whose hashes hold still. `metaChunk: false` in the site's own config wins.
+- An RSS feed, written at the end of the build when `augmentConfig` is given a `feed`
+  option: the pages of a section, newest first, with their excerpt as the entry text.
+  Announced are pages carrying a `date` — a feed is a chronology, and an entry a reader
+  cannot place in it is noise. Absolute links need a hostname, taken from
+  `sitemap.hostname` unless the feed names its own; without one the build says so and
+  writes nothing. Several feeds may be declared, one per language say. The feed is
+  compiled from the page hierarchy and is unrelated to `:::pagelist` — a page may appear
+  in three lists and in the feed, in the feed alone, or in neither.
+- Front matter `hide` names surfaces: `"menu"`, `"breadcrumb"`, `"list"`, `"feed"`, a
+  list of several, or `true` for all of them. A page can now be kept out of the
+  navigation and the feed while staying in the lists.
+- `:::pagelist` pages its entries in the browser with `per-page`: only the current page's
+  entries are rendered, the page shown is remembered as `?page=2` so returning from an
+  entry lands where the reader left off, and the pager is a labelled `<nav>` with a
+  status line and buttons.
+- New built-in section `:::pagelist`, rendered by `<ScavoldPageList>`: links a
+  configurable number of the site's own pages — the latest posts of a blog, a section's
+  sub-pages, a list of downloads. Which pages are listed is addressed as in
+  `<ScavoldMenu>` (`from`, `from-root`, `from-path`, plus `deep` for pages filed in
+  sub-folders), and `limit`, `offset`, `sort` and `reverse` decide which of them appear
+  in what order. Entries are a plain list of links by default; the `teaser`, `images`,
+  `dates` and `heading-level` arguments turn them into teaser cards. Anything written
+  inside the block is rendered above the list. Each entry is a single link around all
+  of its parts, so a screen reader announces it once rather than three times.
+- Pages carry teaser data on their hierarchy node, so a list shows content maintained
+  in the target page rather than repeated in the list: `date` (normalised to an ISO
+  timestamp and rendered in UTC, so a date-only value never shifts a day), `excerpt` —
+  from `excerpt` or `description` front matter, otherwise derived from the page's
+  opening prose and trimmed at a word boundary — and `image`, from `image` front matter
+  or the first image in the page body. Front matter images now go through the
+  responsive image pipeline too, which no pass reached before, as no Markdown syntax
+  reveals them.
+- `.cratly.config.yaml` accepts `excerpt_length` (default `200`) to control how long
+  derived excerpts get; `0` switches the derivation off for sites that would rather not
+  carry it in every page's payload.
+- Front matter `hide` accepts `"list"`, hiding a page from page lists only — a draft
+  post stays reachable by URL without being teased anywhere.
+- `useHierarchy()` exposes `collectPages()`, `nodeHref()`, `nodeLabel()` and
+  `nodeTitle()`, the last two separating the short navigation text menus want from the
+  full title a teaser heading wants. `<ScavoldMenuItems>` uses them instead of its own
+  copies.
+
 ## [0.2.0-rc.3] — 2026-08-09
 
 ### Added
@@ -91,6 +179,7 @@ First published release. Version `0.1.0` existed in-tree only.
 - Only images are processed out of `media_folder`; other file types (video, documents)
   are never copied into the build output and have to live in the static folder.
 
+[0.2.0-rc.4]: https://gitlab.com/cepharum-foss/cratly/scavold/-/compare/v0.2.0-rc.3...v0.2.0-rc.4
 [0.2.0-rc.3]: https://gitlab.com/cepharum-foss/cratly/scavold/-/compare/v0.2.0-rc.2...v0.2.0-rc.3
 [0.2.0-rc.2]: https://gitlab.com/cepharum-foss/cratly/scavold/-/compare/v0.2.0-rc.1...v0.2.0-rc.2
 [0.2.0-rc.1]: https://gitlab.com/cepharum-foss/cratly/scavold/-/tags/v0.2.0-rc.1

package/COMPONENTS.md

@@ -72,9 +72,12 @@ A page can opt out of appearing in menus by setting `hide` in its front matter:
 | Value | Effect |
 |---|---|
 | `false` / absent | Visible everywhere (default) |
-| `true` | Hidden in menus **and** breadcrumbs |
-| `"menu"` | Hidden in menus only |
-| `"breadcrumb"` | Hidden in breadcrumbs only |
+| `true` | Kept off every surface: menus, breadcrumbs, page lists and the feed |
+| `"menu"` | Kept out of menus only |
+| `"breadcrumb"` | Kept out of breadcrumbs only |
+| `"list"` | Kept out of page lists only |
+| `"feed"` | Left out of the RSS feed only |
+| `[ "menu", "feed" ]` | Kept off exactly the surfaces named |
 
 ```yaml
 ---
@@ -460,6 +463,141 @@ const { src, poster, autoplay, loop, muted, preload, overlay, controls } = useVi
 
 ---
 
+### `<ScavoldPageList>`
+
+Links a configurable number of the site's own pages — the latest posts of a blog, a
+teaser row of a section's sub-pages, a list of downloads. Rendered for the
+`:::pagelist` container block. Anything written inside the block (a heading, an
+introduction) is rendered above the list; the list itself is left out when no page
+matches.
+
+Every entry can carry, besides its title, a date, an introductory text and a teaser
+image. All three come from the **target** page, so authors maintain them where the
+content lives instead of repeating them in the list.
+
+#### Markdown syntax
+
+A plain list of links, as a footer or sitemap-style block would use:
+
+```markdown
+::: pagelist from=1 limit=10
+:::
+```
+
+Teaser cards for the five most recent posts:
+
+```markdown
+::: pagelist from=1 limit=5 sort=date teaser images dates heading-level=3 label="Recent posts"
+## Recent posts
+
+Everything we published lately.
+:::
+```
+
+#### Arguments
+
+Which pages are listed:
+
+| Argument | Type | Default | Description |
+|---|---|---|---|
+| `from` | `number` | `1` | Level relative to the current page. `1` = its sub-pages, `0` = its siblings, `-1` = the aunt/uncle level. Same addressing as `<ScavoldMenu>`. |
+| `from-root` | `number` | — | Absolute level from the site root: `1` = top-level pages, `2` = second level. Takes precedence over `from`. |
+| `from-path` | `string` | — | Path of the page whose sub-pages are listed, regardless of where the block sits. Supports the `{locale}` and `{lang}` placeholders. Takes precedence over both other selectors. |
+| `deep` | flag | — | List pages from every level below the selected one, flattened into one list — for posts filed in year or month folders. |
+| `limit` | `number` | `5`, or `0` with `per-page` | Maximum number of entries. `0` lists every page found. A paginated list reaches every page it found unless a limit says otherwise. |
+| `offset` | `number` | `0` | Entries to skip at the start, so a second block can continue where the first one ended. |
+| `sort` | `"order" \| "date" \| "date-asc" \| "title"` | `"order"` | `order` follows the site structure (the `order` front matter and file names), `date` is newest first, `title` is alphabetical in the page's locale. |
+| `reverse` | flag | — | Reverse whichever order was selected. |
+
+What each entry shows:
+
+| Argument | Type | Default | Description |
+|---|---|---|---|
+| `teaser` | flag | — | Show the introductory text of each listed page. |
+| `images` | flag | — | Show the teaser image of each listed page. |
+| `dates` | flag | — | Show the publication date of each listed page. |
+| `date-style` | `"short" \| "medium" \| "long" \| "full" \| "iso"` | `"long"` | Style of the dates. The `Intl.DateTimeFormat` styles follow the page's language; `iso` writes `2020-10-20` in every language. |
+| `time-style` | `"short" \| "medium" \| "long" \| "full" \| "iso"` | — | Style of the time of day. Left out, entries show their date only. `iso` writes `12:16`. |
+| `timezone` | `string` | `"UTC"` | IANA name of the zone the dates are read in, e.g. `Europe/Berlin`. A date carrying no time of day belongs in UTC, the zone the build normalises it into; a list that shows times wants the zone the site publishes from. |
+| `heading-level` | `number` | `0` | Heading level of the entry titles. `0` keeps the entries a plain list of links; use `2`–`6` for teaser cards, one level below the heading above the list. |
+| `image-sizes` | `string` | `"(min-width: 60rem) 30rem, 90vw"` | CSS `sizes` descriptor for the teaser images. Set it to match the column the list is shown in — see [Responsive images](#responsive-images-let-components-own-sizes-not-content-authors). |
+| `label` | `string` | — | Accessible label (`aria-label`) for the list. Set it whenever more than one list appears on the same page so screen readers can tell them apart. |
+| `per-page` | `number` | `0` | Entries per page. `0` shows all of them; anything higher adds a pager. |
+| `param` | `string` | `"page"` | Query parameter the current page is remembered in. Only needs setting when one page carries several paginated lists. |
+
+Pages without a date sort last in both date orders — an undated page is not the
+oldest one, it is unplaced.
+
+#### Where the entry data comes from
+
+| Shown | Read from the target page |
+|---|---|
+| Title | `title` front matter, then `label`, then the first `#` heading, then the path segment. The full `title` wins here, unlike in menus, where the short `label` does. |
+| Date | `date` front matter, normalised to an ISO timestamp. `date: 2026-06-21` is enough; it is rendered in UTC so a date-only value never shifts to the neighbouring day. |
+| Text | `excerpt` front matter, then `description`, otherwise derived from the page's opening prose and trimmed at a word boundary — see [`excerpt_length`](./docs/reference/config.md#excerpt-length). |
+| Image | `image` front matter, otherwise the first image in the page body. Both go through the responsive image pipeline. |
+
+A page opts out of every list with `hide: list` (or `hide: true`) in its front
+matter. The page holding the list is never an entry of it.
+
+#### Rendered markup
+
+```html
+<div class="scavold-pagelist">
+  <!-- slot content: heading, introduction, … -->
+  <ul class="scavold-pagelist__items" aria-label="Recent posts">
+    <li class="scavold-pagelist__item">
+      <a class="scavold-pagelist__link" href="/blog/newest">
+        <picture class="scavold-pagelist__image">…</picture>
+        <h3 class="scavold-pagelist__title">Newest post</h3>
+        <time class="scavold-pagelist__date" datetime="2026-06-21T00:00:00.000Z">21 June 2026</time>
+        <p class="scavold-pagelist__excerpt">Opening prose of the post…</p>
+      </a>
+    </li>
+  </ul>
+</div>
+```
+
+Each entry is a **single** link around all of its parts: image, title, date and text
+address the same page, and separate links would make a screen reader announce every
+entry three times over. The teaser image is therefore decorative (`alt=""`) — the
+title inside the same link is the accessible name.
+
+The component ships no CSS at all; the class names above are the hooks a theme styles.
+
+#### Pagination
+
+`per-page` turns the list into pages, and it happens entirely in the browser: every entry
+is already part of the page's data, so turning a page is slicing an array — nothing is
+fetched, and only the current page's entries are in the document, which keeps the images
+of the others out of it.
+
+```markdown
+::: pagelist from=1 sort=date per-page=10 teaser images dates heading-level=3
+## Archive
+:::
+```
+
+The page shown is remembered in the address bar as `?page=2`, written with
+`history.replaceState`: turning pages is not a step the back button should have to walk
+through, while returning from an entry lands the reader where they left off. A page
+carrying several paginated lists gives each one its own `param`.
+
+What the reader gets is a `<nav>` labelled for screen readers, a status line saying which
+page of how many is shown, and buttons — not links, because no navigation happens and a
+link would promise a URL the built site does not serve. Every part carries a class and no
+styling; the theme decides how a pager looks.
+
+Two consequences worth knowing. The pre-rendered HTML always holds page 1, so arriving
+through a shared `?page=3` link shows the first page for an instant before the browser
+catches up — returning from an entry inside the site does not, that being client-side
+navigation. And entries beyond the first page are not in the HTML, so a crawler that
+executes no JavaScript will not see those links; the sitemap and the
+[feed](./docs/reference/config.md#optionsfeed--an-rss-feed-for-the-site) are what makes
+them discoverable.
+
+---
+
 ### `<ScavoldImage>`
 
 Renders a responsive `<picture>` element for local images. Not intended for direct
@@ -565,10 +703,14 @@ Must be called inside a component's `setup` function (or `<script setup>`).
 | `ancestorAtDepth` | `(node, targetDepth) => HierarchyNode \| undefined` | Returns the ancestor of `node` at `targetDepth` levels below root. Used by `ScavoldMenu` for `from-root` mode. Returns `undefined` if `node` is not deep enough. |
 | `isOnActivePath` | `(node) => boolean` | Returns `true` if `node` is the current page or one of its ancestors |
 | `collectItems` | `(parent, depth, activeOnly, expand) => MenuItem[]` | Recursively collects menu items from `parent`'s children. Used internally by `ScavoldMenu`. |
+| `collectPages` | `(parent, deep?) => HierarchyNode[]` | Collects the pages below `parent` as a flat array in hierarchy order, skipping pages hidden from lists. With `deep` it descends through every level. Used internally by `ScavoldPageList`. |
 | `collectAncestors` | `(includeCurrent, includeRoot) => MenuItem[]` | Returns the ancestor chain from root to the current page as a flat `MenuItem` array. Used internally by `ScavoldBreadcrumb`. |
 | `currentLocale` | `ComputedRef<string>` | The resolved locale for the current page. Falls back to the browser locale when no page or ancestor declares one. |
 | `collectLocaleLinks` | `(detection, includeCurrent?) => LocaleLink[]` | Returns available locale links for the current page. See `ScavoldLocaleMenu` for detection mode details. |
 | `resolveByPath` | `(rawPath: string) => HierarchyNode \| undefined` | Resolves a path string to a hierarchy node. Supports `{locale}` (full BCP 47 tag) and `{lang}` (primary language subtag) placeholders. Tries the interpolated path as-is, then with `/index.md`, then with `.md` appended. |
+| `nodeHref` | `(node) => string` | Root-relative link target of a node, preferring its alias URL. Every page is linked as the file it is built into: `/blog/post.html`, a folder's index page as `/blog/index.html`, the site's own as `/index.html`. |
+| `nodeLabel` | `(node) => string` | Navigation text of a node: `label`, then `title`, then the path segment. For menus and breadcrumbs, where space is scarce. |
+| `nodeTitle` | `(node) => string` | Full text of a node: `title`, then `label`, then the path segment. For entries that stand on their own, such as a teaser heading. |
 
 #### `HierarchyNode` properties
 
@@ -577,13 +719,17 @@ Must be called inside a component's `setup` function (or `<script setup>`).
 | `path` | `string` | Relative path of the Markdown source file |
 | `isPage` | `boolean` | `true` for actual pages, `false` for intermediate folder nodes |
 | `frontmatter` | `object` | Parsed front matter data |
-| `frontmatter.hide` | `boolean \| "menu" \| "breadcrumb"` | Excludes this node from menus, breadcrumbs, or both. See [Hiding pages via front matter](#hiding-pages-via-front-matter). |
+| `frontmatter.hide` | `boolean \| string \| string[]` | Surfaces this node is kept off: `"menu"`, `"breadcrumb"`, `"list"`, `"feed"`, a list of them, or `true` for all. See [Hiding pages via front matter](#hiding-pages-via-front-matter). |
 | `frontmatter.order` | `number?` | Sort position among siblings. Pages with a lower value appear first; pages without `order` follow in filename order. |
 | `frontmatter.url` | `string?` | Alias output path. When set, VitePress builds the page at this URL instead of the path derived from the source file. Conflicts (two pages with the same alias) are a build error. |
 | `title` | `string?` | Display title — from frontmatter `title` or the first `#` heading |
 | `label` | `string?` | Navigation label — from frontmatter `label`; falls back to `title` in menus |
 | `url` | `string?` | Normalised alias output path (e.g. `de/impressum.md`) when `frontmatter.url` is set. Used by `nodeHref` as the page's href. |
 | `locale` | `string?` | Resolved locale (BCP 47), inherited from ancestors |
+| `excerpt` | `string?` | Introductory text — from frontmatter `excerpt` or `description`, else derived from the page's opening prose |
+| `image` | `string?` | Lead image reference as the author wrote it — from frontmatter `image`, else the first image in the page |
+| `imageData` | `{ src, srcset, webpSrcset }?` | Responsive variant data for `image`, resolved at build time. Carries no `sizes` value: that belongs to the component showing the image. |
+| `date` | `string?` | Publication date as an ISO 8601 timestamp — from frontmatter `date` |
 | `parent` | `HierarchyNode?` | Parent node — non-enumerable, not serialised to JSON |
 | `subs` | `object?` | Child nodes keyed by path segment, sorted by `order` then filename |
 
@@ -661,6 +807,101 @@ Spread into `defineProps` to declare all video-related props at once.
 
 ---
 
+### `usePageList( props )`
+
+```js
+import { usePageList, pageListProps } from "scavold/composables/usePageList.js";
+```
+
+Composable for custom page-list components — the way a theme renders lists its own
+way instead of restyling Scavold's markup. Write a component, declare
+`pageListProps`, call the composable and render whatever the design asks for; map a
+container name to it in the site's configuration:
+
+```yaml
+# .cratly.config.yaml
+containers:
+  postlist:
+    label: "Posts, our way"
+    component: SitePostList
+```
+
+```js
+// .vitepress/theme/index.js — register it after Scavold's own components
+async function enhanceApp( context ) {
+	await scavoldEnhanceApp( context );
+
+	context.app.component( "SitePostList", SitePostList );
+}
+```
+
+Selection, ordering, paging and timestamp rendering stay Scavold's; only the markup
+is the theme's. Registering a component under a name Scavold already uses
+(`ScavoldPageList`) replaces that one everywhere instead. Resolves the `:::pagelist` container props
+into the entries to render, each carrying its link target, title, date, introductory
+text and responsive teaser image data — see the
+[arguments](#scavoldpagelist) for what each prop means.
+
+#### `pageListProps`
+
+Spread into `defineProps` to declare all page-list props at once. Each container
+argument arrives as `data…`, in the same way as `videoProps`: `dataFrom` for `from=…`,
+`dataHeadingLevel` for `heading-level=…`, `dataTeaser` for the `teaser` flag, and so on.
+
+#### Returns
+
+| Name | Type | Description |
+|---|---|---|
+| `items` | `ComputedRef<PageListItem[]>` | The selected, ordered and limited entries |
+| `headingTag` | `ComputedRef<string \| null>` | `"h2"`…`"h6"` when a heading level was requested, `null` for a plain list of links |
+| `teaser` | `ComputedRef<boolean>` | `true` when the `teaser` flag is set |
+| `images` | `ComputedRef<boolean>` | `true` when the `images` flag is set |
+| `dates` | `ComputedRef<boolean>` | `true` when the `dates` flag is set |
+| `imageSizes` | `ComputedRef<string>` | CSS `sizes` descriptor for the teaser images |
+| `ariaLabel` | `ComputedRef<string \| undefined>` | Accessible label for the list, `undefined` when the author set none |
+| `formatDate` | `(isoDate: string) => string` | Renders a timestamp in the styles and zone the list was given |
+| `page` | `Ref<number>` | Page currently shown, `1` before the browser reads the query |
+| `pages` | `ComputedRef<number[]>` | Page numbers to offer, `[ 1 ]` for an unpaginated list |
+| `pageCount` | `ComputedRef<number>` | Number of pages the selection divides into |
+| `goToPage` | `(page: number) => void` | Turns to a page and remembers it in the URL |
+
+#### `PageListItem` properties
+
+| Property | Type | Description |
+|---|---|---|
+| `node` | `HierarchyNode` | The listed page's hierarchy node |
+| `href` | `string` | Root-relative link target, alias URL included |
+| `title` | `string` | Full title of the page (`title` wins over `label` here) |
+| `date` | `string?` | ISO 8601 publication date, when the page declares one |
+| `excerpt` | `string?` | Introductory text, when the page has or yields one |
+| `image` | `{ src, srcset, webpSrcset }?` | Responsive variant data of the teaser image |
+
+---
+
+### `formatTimestamp( timestamp, options )`
+
+```js
+import { formatTimestamp } from "scavold/lib/dateFormat.js";
+```
+
+Renders a timestamp the way page lists do, for a theme's own components — a byline
+under a post's title, for instance. Free of Vue and VitePress, so build-time code can
+use it too.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `locale` | `string` | the runtime's | Locale to phrase the result in |
+| `dateStyle` | `"short" \| "medium" \| "long" \| "full" \| "iso"` | `"long"` | Style of the date; `iso` writes `2020-10-20` in every language |
+| `timeStyle` | same values | — | Style of the time of day; omitted, only the date is rendered |
+| `timeZone` | `string` | `"UTC"` | IANA name of the zone the timestamp is read in |
+
+The result depends on the arguments alone, never on the machine it runs on, so
+pre-rendered markup and the browser agree — a timestamp that changes on hydration
+would tear the markup apart. A timestamp that cannot be read renders as an empty
+string rather than as `Invalid Date`.
+
+---
+
 ### `useContainer( props )`
 
 ```js

package/FRONTMATTER.md

@@ -162,18 +162,86 @@ emits a warning and the explicit declaration takes precedence.
 
 ---
 
+## `date`
+
+**Type:** `string` (ISO 8601) — e.g. `2026-06-21` or `2026-06-21T14:30:00Z`
+
+Publication date of the page. Read by [`<ScavoldPageList>`](./COMPONENTS.md#scavoldpagelist)
+to order entries chronologically and to show a date per entry, and by the site's RSS feed,
+which announces only pages that carry one.
+
+```yaml
+---
+date: 2026-06-21
+---
+```
+
+A date-only value is normalised to midnight UTC and rendered in UTC as well, so it
+never shows up as the neighbouring day in another time zone. Pages without a date
+sort last in both date orders.
+
+---
+
+## `excerpt` / `description`
+
+**Type:** `string`
+
+Introductory text shown for this page wherever it is teased — in a
+[`<ScavoldPageList>`](./COMPONENTS.md#scavoldpagelist) with the `teaser` flag, for
+example.
+
+```yaml
+---
+excerpt: Wie wir den Schulhof an einem Nachmittag umgestaltet haben.
+---
+```
+
+When neither key is declared, Scavold derives the text from the page's opening prose
+at build time: headings, images, code and container fences are dropped, the remaining
+text is trimmed to [`excerpt_length`](./docs/reference/config.md#excerpt-length)
+characters at a word boundary and marked with an ellipsis. Declaring `excerpt` is
+therefore an override, not a prerequisite.
+
+`description` is accepted as an alias, since sites often already maintain it for
+search engines. `excerpt` wins when both are present.
+
+---
+
+## `image`
+
+**Type:** `string` — path relative to the media folder
+
+Lead image of the page, used as its teaser image in a
+[`<ScavoldPageList>`](./COMPONENTS.md#scavoldpagelist) with the `images` flag.
+
+```yaml
+---
+image: /schulhof.jpg
+---
+```
+
+The file goes through the responsive image pipeline like any image in a page body, so
+a teaser gets the same `srcset` and WebP variants. When the key is absent, the first
+image in the page body is used instead.
+
+---
+
 ## `hide`
 
-**Type:** `boolean | "menu" | "breadcrumb"`
+**Type:** `boolean | "menu" | "breadcrumb" | "list" | "feed" | string[]`
 
-Controls whether this page appears in menus, breadcrumbs, or both.
+Controls the surfaces this page appears on. Each value names one of them; `true` covers
+all — which is what an unfinished post wants, reachable by URL and announced nowhere.
 
 | Value | Effect |
 |---|---|
 | `false` or absent | Visible everywhere (default) |
-| `true` | Hidden in both menus and breadcrumbs |
+| `true` | Hidden everywhere: menus, breadcrumbs, page lists and the feed |
 | `"menu"` | Hidden in menus only |
 | `"breadcrumb"` | Hidden in breadcrumbs only |
+| `"list"` | Hidden in page lists only |
+| `"feed"` | Left out of the RSS feed only |
+| `[ "menu", "feed" ]` | Kept off exactly the surfaces named |
 
 ```yaml
 ---

package/components/ScavoldLocaleMenu.vue

@@ -41,7 +41,7 @@ const props = withDefaults( defineProps<LocaleMenuProps>(), {
 	label: undefined,
 } );
 
-const { collectLocaleLinks, currentLocale } = useHierarchy();
+const { collectLocaleLinks } = useHierarchy();
 const { t } = useScavoldI18n();
 
 const links = computed<Scavold.LocaleLink[]>( () =>

package/components/ScavoldLocaleRedirect.vue

@@ -13,7 +13,7 @@ const { frontmatter } = useData();
  * @returns {string|null}
  */
 function pickTarget( map ) {
-	for ( const lang of ( navigator.languages ?? [] ) ) {
+	for ( const lang of navigator.languages ?? [] ) {
 		// exact match first (e.g. "de-AT" → "de-AT")
 		if ( map[lang] ) return map[lang];
 		// prefix match (e.g. "de-AT" → "de")

package/components/ScavoldMenuItems.vue

@@ -1,28 +1,12 @@
 <script setup lang="ts">
+import { useHierarchy } from "../composables/hierarchy";
 import type { Scavold } from "../index";
 
 defineProps<{
 	items: Scavold.MenuItem[];
 }>();
 
-function label( node: Scavold.HierarchyNode ): string {
-	if ( node.label ) return node.label;
-	if ( node.title ) return node.title;
-
-	// Fall back to the last meaningful path segment (strip index.md, extension)
-	const segment = node.path
-		.replace( /\/index\.md$/, "" )
-		.replace( /\.md$/, "" )
-		.split( "/" )
-		.filter( Boolean )
-		.pop();
-
-	return segment ?? node.path;
-}
-
-function href( node: Scavold.HierarchyNode ): string {
-	return "/" + ( node.url ?? node.path ).replace( /\.md$/, "" ).replace( /\/index$/, "/" );
-}
+const { nodeLabel, nodeHref } = useHierarchy();
 </script>
 
 <template>
@@ -35,7 +19,7 @@ function href( node: Scavold.HierarchyNode ): string {
         current: item.current,
       }"
     >
-      <a :href="href( item.node )" :aria-current="item.current ? 'page' : undefined">{{ label( item.node ) }}</a>
+      <a :href="nodeHref( item.node )" :aria-current="item.current ? 'page' : undefined">{{ nodeLabel( item.node ) }}</a>
       <ScavoldMenuItems
         v-if="item.children.length"
         :items="item.children"

package/components/ScavoldPageList.vue

@@ -0,0 +1,110 @@
+<script setup>
+import { computed } from "vue";
+import { useContainer } from "../composables/useContainer.js";
+import { usePageList, pageListProps } from "../composables/usePageList.js";
+import { useScavoldI18n } from "../composables/useI18n.js";
+import ScavoldImage from "./ScavoldImage.vue";
+
+const props = defineProps( pageListProps );
+
+const { classes, dataAttrs } = useContainer( props );
+const {
+	items, headingTag, teaser, images, dates, imageSizes, ariaLabel, formatDate,
+	page, pages, pageCount, goToPage,
+} = usePageList( props );
+const { t } = useScavoldI18n();
+
+const pagerLabel = t( "nav.pages" );
+const previousLabel = t( "pagelist.previous" );
+const nextLabel = t( "pagelist.next" );
+const status = t( "pagelist.status", computed( () => ( { current: page.value, total: pageCount.value } ) ) );
+</script>
+
+<template>
+  <div class="scavold-pagelist" :class="classes" v-bind="dataAttrs">
+    <!-- whatever the author wrote inside the section: a heading, an intro, anything -->
+    <slot />
+
+    <ul
+      v-if="items.length"
+      class="scavold-pagelist__items"
+      :aria-label="ariaLabel"
+    >
+      <li
+        v-for="item of items"
+        :key="item.node.path"
+        class="scavold-pagelist__item"
+      >
+        <!-- One link per entry rather than one per element: image, title, date and text
+             all address the same page, and repeating that target would make a screen
+             reader announce every entry three times. -->
+        <a class="scavold-pagelist__link" :href="item.href">
+          <ScavoldImage
+            v-if="images && item.image"
+            class="scavold-pagelist__image"
+            :src="item.image.src"
+            :srcset="item.image.srcset"
+            :webp-srcset="item.image.webpSrcset"
+            :sizes="imageSizes"
+            alt=""
+          />
+
+          <component
+            :is="headingTag"
+            v-if="headingTag"
+            class="scavold-pagelist__title"
+          >{{ item.title }}</component>
+          <span v-else class="scavold-pagelist__title">{{ item.title }}</span>
+
+          <time
+            v-if="dates && item.date"
+            class="scavold-pagelist__date"
+            :datetime="item.date"
+          >{{ formatDate( item.date ) }}</time>
+
+          <p
+            v-if="teaser && item.excerpt"
+            class="scavold-pagelist__excerpt"
+          >{{ item.excerpt }}</p>
+        </a>
+      </li>
+    </ul>
+
+    <!-- Turning a page swaps content in place, so the reader is told which page they are
+         on rather than being left to notice. Buttons, not links: no navigation happens,
+         and a link would promise a page the built site does not serve. -->
+    <nav
+      v-if="pageCount > 1"
+      class="scavold-pagelist__pager"
+      :aria-label="pagerLabel"
+    >
+      <p class="scavold-pagelist__status" role="status">{{ status }}</p>
+
+      <button
+        type="button"
+        class="scavold-pagelist__page scavold-pagelist__page--previous"
+        :disabled="page <= 1"
+        :aria-label="previousLabel"
+        @click="goToPage( page - 1 )"
+      >&lsaquo;</button>
+
+      <button
+        v-for="number of pages"
+        :key="number"
+        type="button"
+        class="scavold-pagelist__page"
+        :class="{ current: number === page }"
+        :aria-current="number === page ? 'page' : undefined"
+        @click="goToPage( number )"
+      >{{ number }}</button>
+
+      <button
+        type="button"
+        class="scavold-pagelist__page scavold-pagelist__page--next"
+        :disabled="page >= pageCount"
+        :aria-label="nextLabel"
+        @click="goToPage( page + 1 )"
+      >&rsaquo;</button>
+    </nav>
+  </div>
+</template>