scavold 0.2.0-rc.4 → 0.2.0-rc.5

package/CHANGELOG.md

@@ -11,6 +11,42 @@ changes may occur in any release.
 
 ### 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
@@ -143,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

@@ -504,7 +504,7 @@ Which pages are listed:
 | `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` | Maximum number of entries. `0` lists every page found. |
+| `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. |
@@ -516,7 +516,9 @@ What each entry shows:
 | `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"` | `"long"` | `Intl.DateTimeFormat` style used for the dates. |
+| `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. |
@@ -706,7 +708,7 @@ Must be called inside a component's `setup` function (or `<script setup>`).
 | `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. |
+| `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. |
 
@@ -808,10 +810,34 @@ Spread into `defineProps` to declare all video-related props at once.
 ### `usePageList( props )`
 
 ```js
-import { usePageList, pageListProps } from "./scavold/composables/usePageList.js";
+import { usePageList, pageListProps } from "scavold/composables/usePageList.js";
 ```
 
-Composable for custom page-list components. Resolves the `:::pagelist` container props
+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.
@@ -833,7 +859,11 @@ argument arrives as `data…`, in the same way as `videoProps`: `dataFrom` for `
 | `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` | Formats a timestamp in the page's locale, in UTC |
+| `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
 
@@ -848,6 +878,30 @@ argument arrives as `data…`, in the same way as `videoProps`: `dataFrom` for `
 
 ---
 
+### `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/composables/hierarchy.ts

@@ -2,6 +2,7 @@ import { useData } from "vitepress";
 import { computed } from "vue";
 import { useL10n } from "@cepharum/vue3-i18n";
 import { hidesFrom } from "../lib/hide.js";
+import { nodePath, pageHref } from "../lib/href.js";
 import type { Scavold } from "../index";
 
 /**
@@ -262,8 +263,7 @@ export function useHierarchy() {
 	 * Converts a hierarchy node path to a root-relative href.
 	 * Prefers node.url (the alias output path) when declared.
 	 */
-	const nodeHref = ( node: Scavold.HierarchyNode ): string =>
-		"/" + ( node.url ?? node.path ).replace( /\.md$/, "" ).replace( /\/index$/, "/" );
+	const nodeHref = ( node: Scavold.HierarchyNode ): string => nodePath( node );
 
 	/**
 	 * The last meaningful segment of a node's source path, used wherever a page
@@ -402,7 +402,7 @@ export function useHierarchy() {
 				if ( translations ) {
 					for ( const [ loc, path ] of Object.entries( translations ) ) {
 						if ( !links.has( loc ) ) {
-							links.set( loc, "/" + String( path ).replace( /\.md$/, "" ).replace( /\/index$/, "/" ) );
+							links.set( loc, pageHref( String( path ) ) );
 						}
 					}
 				}

package/composables/useI18n.js

@@ -1,5 +1,32 @@
 import { useL10n } from "@cepharum/vue3-i18n";
 
+import de from "../l10n/de.json";
+import en from "../l10n/en.json";
+
+/**
+ * Scavold's own translations, keyed by language. They are part of the bundle on
+ * purpose: fetching them at runtime would have to name a URL, and a package that
+ * ships as source inside another site's build cannot know one. Each file is a few
+ * hundred bytes, and a site is free to override any key through its own loader.
+ */
+const TRANSLATIONS = { de, en };
+
+/** Language served to anyone whose locale Scavold does not translate. */
+const FALLBACK_LOCALE = "en";
+
+/**
+ * Picks the translations for a locale, accepting regional tags: `de-AT` is served
+ * the German set rather than falling through to English.
+ *
+ * @param {string} locale locale tag as requested by the l10n context
+ * @returns {object} set of translations
+ */
+export function translationsFor( locale ) {
+	const language = String( locale ?? "" ).toLowerCase().split( /[-_]/ )[0];
+
+	return TRANSLATIONS[language] ?? TRANSLATIONS[FALLBACK_LOCALE];
+}
+
 /**
  * Registers Scavold's built-in translations into the shared l10n context under
  * the `@scavold` namespace. All keys are accessed as `@scavold.<key>`.
@@ -13,9 +40,7 @@ import { useL10n } from "@cepharum/vue3-i18n";
  */
 export function registerScavoldI18n() {
 	useL10n().setNamespaceLoader( "@scavold", locale =>
-		import( `../l10n/${locale}.json` ).catch( () =>
-			import( "../l10n/en.json" )
-		)
+		Promise.resolve( translationsFor( locale ) )
 	);
 }
 

package/composables/usePageList.js

@@ -1,6 +1,8 @@
 import { computed, onMounted, ref } from "vue";
 import { containerProps } from "./useContainer.js";
 import { useHierarchy } from "./hierarchy";
+import { formatTimestamp, TIMESTAMP_STYLES, DEFAULT_TIMEZONE } from "../lib/dateFormat.js";
+import { asNumber, selectionLimit } from "../lib/pageList.js";
 
 /**
  * Props definition for page-list container components. Spread into `defineProps`
@@ -49,9 +51,20 @@ export const pageListProps = {
 	/** Show the publication date of each listed page. */
 	dataDates: { type: String, default: null },
 
-	/** Intl date style for the dates: "short", "medium", "long" or "full". */
+	/** Style of the dates: "short", "medium", "long", "full" — as Intl formats them
+	 * in the page's locale — or "iso" for the locale-independent 2020-10-20. */
 	dataDateStyle: { type: String, default: null },
 
+	/** Style of the time of day, in the same values as `data-date-style`. Left out,
+	 * entries show their date only. */
+	dataTimeStyle: { type: String, default: null },
+
+	/** IANA name of the zone the dates are read in, e.g. "Europe/Berlin". Defaults
+	 * to UTC, the zone dates are normalised into at build time — which is what a
+	 * date without a time of day should be shown in. A list that shows times wants
+	 * the zone the site publishes from instead. */
+	dataTimezone: { type: String, default: null },
+
 	/** Heading level of the entry titles, 2–6. 0 renders a plain list of links. */
 	dataHeadingLevel: { type: String, default: null },
 
@@ -75,21 +88,8 @@ export const pageListProps = {
 /** Orders a page list understands. */
 const SORT_ORDERS = new Set( [ "order", "date", "date-asc", "title" ] );
 
-/** Date styles Intl.DateTimeFormat accepts. */
-const DATE_STYLES = new Set( [ "short", "medium", "long", "full" ] );
-
-/**
- * Reads a container argument that carries a number.
- *
- * @param {string|null} value raw attribute value
- * @param {number} fallback value to use when absent or unusable
- * @returns {number}
- */
-function asNumber( value, fallback ) {
-	const parsed = Number.parseInt( value, 10 );
-
-	return Number.isNaN( parsed ) ? fallback : parsed;
-}
+/** Styles a page list renders its dates in. */
+const DATE_STYLES = new Set( TIMESTAMP_STYLES );
 
 /**
  * Compares two nodes by date, newest first. Pages without a date sort last, in
@@ -130,7 +130,7 @@ export function usePageList( props ) {
 	const deep = computed( () => props.dataDeep != null );
 	const reverse = computed( () => props.dataReverse != null );
 
-	const limit = computed( () => Math.max( 0, asNumber( props.dataLimit, 5 ) ) );
+	const limit = computed( () => selectionLimit( props.dataLimit, props.dataPerPage ) );
 	const offset = computed( () => Math.max( 0, asNumber( props.dataOffset, 0 ) ) );
 
 	const sort = computed( () =>
@@ -141,6 +141,14 @@ export function usePageList( props ) {
 		( DATE_STYLES.has( props.dataDateStyle ) ? props.dataDateStyle : "long" )
 	);
 
+	// No time of day unless the list asks for one: most lists date an entry, they do
+	// not timestamp it.
+	const timeStyle = computed( () =>
+		( DATE_STYLES.has( props.dataTimeStyle ) ? props.dataTimeStyle : null )
+	);
+
+	const timezone = computed( () => props.dataTimezone || DEFAULT_TIMEZONE );
+
 	// A plain list of links carries no headings; teaser cards do, and their level
 	// has to fit the document outline around them, which only the author knows.
 	const headingTag = computed( () => {
@@ -313,29 +321,18 @@ export function usePageList( props ) {
 	const pages = computed( () => Array.from( { length: pageCount.value }, ( _, index ) => index + 1 ) );
 
 	/**
-	 * Formats an ISO timestamp for display in the current page's locale. Dates are
-	 * rendered in UTC, the zone they were normalised into at build time, so a
-	 * date-only front matter value never shifts to its neighbouring day.
+	 * Renders an entry's timestamp in the styles and zone the list was given.
 	 *
 	 * @param {string} isoDate ISO 8601 timestamp
 	 * @returns {string}
 	 */
 	function formatDate( isoDate ) {
-		const date = new Date( isoDate );
-
-		if ( Number.isNaN( date.getTime() ) ) {
-			return "";
-		}
-
-		try {
-			return new Intl.DateTimeFormat( currentLocale.value || undefined, {
-				dateStyle: dateStyle.value,
-				timeZone: "UTC",
-			} ).format( date );
-		} catch {
-			// An unusable locale tag must not take the page down with it.
-			return date.toISOString().slice( 0, 10 );
-		}
+		return formatTimestamp( isoDate, {
+			locale: currentLocale.value || undefined,
+			dateStyle: dateStyle.value,
+			timeStyle: timeStyle.value,
+			timeZone: timezone.value,
+		} );
 	}
 
 	return {

package/lib/config.js

@@ -9,6 +9,7 @@ import { patchRenderer } from "./markdown.js";
 import { extractContainerMediaSrcs, mediaPropsOf, registerContainers, resolveContainerMap } from "./containers.js";
 import { buildSectionManifest, writeSectionManifest } from "./sectionManifest.js";
 import { isExternalUrl, servableRedirectTarget } from "./redirectTarget.js";
+import { pageHref, servableUrl } from "./href.js";
 
 // Scavold's own version, reported under `adapter.version` in the emitted
 // section-type manifest.
@@ -417,6 +418,19 @@ export async function augmentConfig( rawConfig, options = {} ) {
 		// site that would rather not can say so in its own config.
 		metaChunk: rawConfig.metaChunk ?? true,
 
+		// The sitemap names the same URL as every link on the site: the page's own file.
+		// VitePress lists a folder's index page as the folder ("/blog/") and the site's
+		// own as "/", which would make the same page appear under two spellings.
+		sitemap: rawConfig.sitemap && {
+			...rawConfig.sitemap,
+
+			transformItems( items ) {
+				const named = items.map( item => ( { ...item, url: servableUrl( `/${item.url}` ).slice( 1 ) } ) );
+
+				return rawConfig.sitemap.transformItems?.( named ) ?? named;
+			},
+		},
+
 		vite: {
 			...resolvedConfig.vite,
 			plugins: [
@@ -473,7 +487,7 @@ export async function augmentConfig( rawConfig, options = {} ) {
 					} else {
 						const dir = dirname( pageData.relativePath );
 						const resolved = joinPosix( dir === "." ? "" : dir, redirect );
-						target = servableRedirectTarget( "/" + resolved.replace( /\/index\.md$/, "/" ).replace( /\.md$/, "" ) );
+						target = pageHref( resolved );
 					}
 					pageData.frontmatter.head = [
 						...pageData.frontmatter.head ?? [] ,

package/lib/dateFormat.js

@@ -0,0 +1,125 @@
+/**
+ * Rendering of timestamps for display.
+ *
+ * Kept free of Vue and VitePress so it can be used from components, from a
+ * theme's own components and from build-time code alike.
+ */
+
+/** Date and time styles Intl.DateTimeFormat accepts. */
+export const INTL_STYLES = [ "short", "medium", "long", "full" ];
+
+/** Style rendering a date as 2020-10-20 and a time as 12:16, in any locale. */
+export const ISO_STYLE = "iso";
+
+/** Styles a timestamp can be rendered in: Intl's own plus the locale-independent one. */
+export const TIMESTAMP_STYLES = [ ...INTL_STYLES, ISO_STYLE ];
+
+/** Zone timestamps are read in unless the caller names another one. Dates are
+ *  normalised into UTC at build time, so a front matter value that carries no time
+ *  of day never shifts to its neighbouring day. */
+export const DEFAULT_TIMEZONE = "UTC";
+
+/**
+ * Reads a timestamp in a named zone, as the numeric fields it consists of.
+ *
+ * @param {Date} date timestamp to read
+ * @param {string} timeZone IANA name of the zone to read it in
+ * @returns {Object<string,string>} fields of the timestamp, zero-padded
+ */
+function zonedParts( date, timeZone ) {
+	const parts = new Intl.DateTimeFormat( "en-GB", {
+		timeZone,
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+		hour: "2-digit",
+		minute: "2-digit",
+		hour12: false,
+	} ).formatToParts( date );
+
+	return Object.fromEntries( parts.map( part => [ part.type, part.value ] ) );
+}
+
+/**
+ * Writes the date of a timestamp as 2020-10-20, in every locale alike.
+ *
+ * @param {Date} date timestamp to write
+ * @param {string} timeZone IANA name of the zone to read it in
+ * @returns {string}
+ */
+export function isoDatePart( date, timeZone ) {
+	const { year, month, day } = zonedParts( date, timeZone );
+
+	return `${year}-${month}-${day}`;
+}
+
+/**
+ * Writes the time of day of a timestamp as 12:16, in every locale alike.
+ *
+ * @param {Date} date timestamp to write
+ * @param {string} timeZone IANA name of the zone to read it in
+ * @returns {string}
+ */
+export function isoTimePart( date, timeZone ) {
+	const { hour, minute } = zonedParts( date, timeZone );
+
+	// Midnight comes back as hour 24 in some engines' en-GB output.
+	return `${hour === "24" ? "00" : hour}:${minute}`;
+}
+
+/**
+ * Renders a timestamp for display.
+ *
+ * The result depends on the arguments only, never on the machine it runs on, so
+ * pre-rendered markup and the browser's own rendering agree — a timestamp that
+ * changes on hydration would tear the markup apart.
+ *
+ * @param {string|Date} timestamp ISO 8601 timestamp, or a date
+ * @param {object} options
+ * @param {string} [options.locale] locale to phrase the result in
+ * @param {string} [options.dateStyle] one of TIMESTAMP_STYLES
+ * @param {string} [options.timeStyle] one of TIMESTAMP_STYLES; omitted, no time of day is shown
+ * @param {string} [options.timeZone] IANA name of the zone to read the timestamp in
+ * @returns {string} rendered timestamp, empty for one that cannot be read
+ */
+export function formatTimestamp( timestamp, {
+	locale = undefined, dateStyle = "long", timeStyle = null, timeZone = DEFAULT_TIMEZONE,
+} = {} ) {
+	const date = timestamp instanceof Date ? timestamp : new Date( timestamp );
+
+	if ( Number.isNaN( date.getTime() ) ) {
+		return "";
+	}
+
+	try {
+		// Intl phrases a date and a time together the way a locale wants them —
+		// "20 October 2020 at 12:16" — so it gets both at once where it can.
+		if ( dateStyle !== ISO_STYLE && timeStyle !== ISO_STYLE ) {
+			const options = { dateStyle, timeZone };
+
+			if ( timeStyle ) {
+				options.timeStyle = timeStyle;
+			}
+
+			return new Intl.DateTimeFormat( locale, options ).format( date );
+		}
+
+		const parts = [
+			dateStyle === ISO_STYLE
+				? isoDatePart( date, timeZone )
+				: new Intl.DateTimeFormat( locale, { dateStyle, timeZone } ).format( date ),
+		];
+
+		if ( timeStyle ) {
+			parts.push( timeStyle === ISO_STYLE
+				? isoTimePart( date, timeZone )
+				: new Intl.DateTimeFormat( locale, { timeStyle, timeZone } ).format( date ) );
+		}
+
+		return parts.join( " " );
+	} catch {
+		// Neither an unusable locale tag nor an unknown zone must take the page down
+		// with it.
+		return date.toISOString().slice( 0, 10 );
+	}
+}

package/lib/feed.js

@@ -1,5 +1,6 @@
 import { forEachPage } from "./pages.js";
 import { hidesFrom } from "./hide.js";
+import { nodePath } from "./href.js";
 
 /** How many entries a feed carries unless the site says otherwise. */
 export const DEFAULT_FEED_LIMIT = 20;
@@ -19,20 +20,6 @@ export function escapeXml( value ) {
 		.replace( /'/g, "'" );
 }
 
-/**
- * Converts a hierarchy node's source path into the path the built site serves, preferring
- * the alias URL when the page declares one.
- *
- * Mirrors nodeHref() of the hierarchy composable, which cannot be shared: that one runs in
- * the browser, this one during the build.
- *
- * @param {object} node hierarchy node of a page
- * @returns {string} root-relative path, e.g. `/de/blog/post`
- */
-export function pagePath( node ) {
-	return "/" + ( node.url ?? node.path ).replace( /\.md$/, "" ).replace( /\/index$/, "/" );
-}
-
 /**
  * Collects the pages a feed announces: everything below the given path that carries a
  * date, newest first.
@@ -91,7 +78,7 @@ export function collectFeedPages( hierarchy, { from = "", limit = DEFAULT_FEED_L
 export function renderRss( { title, description = "", hostname, path, pages, now = new Date() } ) {
 	const origin = String( hostname ).replace( /\/$/, "" );
 	const items = pages.map( node => {
-		const link = origin + pagePath( node );
+		const link = origin + nodePath( node );
 		const text = node.excerpt ?? "";
 
 		return [

package/lib/href.js

@@ -0,0 +1,62 @@
+/**
+ * The URL a page is served under.
+ *
+ * Kept free of Vue and VitePress: the same rule is needed in the browser, where menus
+ * and breadcrumbs link pages, and during the build, where the feed, the sitemap and
+ * the redirects name them. Two copies of a rule are two chances to get it wrong — the
+ * site's own index page used to be linked as `/index`, a URL no server has to answer.
+ *
+ * Every page is linked as the file it is built into, extension and all: `/blog/` and
+ * `/blog/post` would be answered by a server that looks for an index file or tries the
+ * `.html` extension, but only after it has looked for something that is not there.
+ * `/blog/index.html` is a hit on the first attempt, and it is the spelling readers are
+ * used to seeing.
+ */
+
+/** Extension every page is built into and therefore linked with. */
+export const PAGE_EXTENSION = ".html";
+
+/**
+ * Converts a page's source path into the root-relative URL the built site serves.
+ *
+ * @param {string} path source path of a page, or the alias URL it declares
+ * @returns {string} root-relative URL, e.g. `/de/blog/post.html` or `/blog/index.html`
+ */
+export function pageHref( path ) {
+	return "/" + String( path ?? "" ).replace( /\.md$/, "" ) + PAGE_EXTENSION;
+}
+
+/**
+ * Converts a hierarchy node into the URL the built site serves it under, preferring
+ * the alias URL when the page declares one.
+ *
+ * @param {object} node hierarchy node of a page
+ * @returns {string} root-relative URL
+ */
+export function nodePath( node ) {
+	return pageHref( node?.url ?? node?.path );
+}
+
+/**
+ * Rewrites a site-relative URL to the file that answers it: a folder URL to the index
+ * page inside it, an extension-less path to its page.
+ *
+ * Left alone are external URLs and anything already naming a file, and a query string
+ * or fragment stays at the end where it belongs.
+ *
+ * @param {string} url URL as written, e.g. in a page's `redirect` front matter
+ * @returns {string} URL naming the file that answers it
+ */
+export function servableUrl( url ) {
+	const [ , path, suffix = "" ] = /^([^?#]*)([?#].*)?$/.exec( String( url ?? "" ) );
+
+	if ( path.endsWith( PAGE_EXTENSION ) ) {
+		return path + suffix;
+	}
+
+	if ( path === "" || path.endsWith( "/" ) ) {
+		return `${path}index${PAGE_EXTENSION}${suffix}`;
+	}
+
+	return path + PAGE_EXTENSION + suffix;
+}

package/lib/pageList.js

@@ -0,0 +1,38 @@
+/**
+ * Rules a page list selects by, kept free of Vue and VitePress so they can be
+ * checked on their own and reused by a theme's own list components.
+ */
+
+/** Entries a list shows when it neither limits nor paginates its selection. */
+export const DEFAULT_LIMIT = 5;
+
+/**
+ * Reads an argument that carries a number.
+ *
+ * @param {string|number|null} value raw attribute value
+ * @param {number} fallback value to use when absent or unusable
+ * @returns {number}
+ */
+export function asNumber( value, fallback ) {
+	const parsed = Number.parseInt( value, 10 );
+
+	return Number.isNaN( parsed ) ? fallback : parsed;
+}
+
+/**
+ * Determines how many pages a list selects before its pager divides them.
+ *
+ * A list that paginates is meant to reach every page it selected: capping the
+ * selection at the default would leave a pager turning one short page. A limit the
+ * author set still wins — it says how far the list reaches, and the pager then
+ * divides that.
+ *
+ * @param {string|number|null} limit `limit` argument as written, if any
+ * @param {string|number|null} perPage `per-page` argument as written, if any
+ * @returns {number} number of entries to select, 0 for all of them
+ */
+export function selectionLimit( limit, perPage ) {
+	const fallback = perPage == null ? DEFAULT_LIMIT : 0;
+
+	return Math.max( 0, asNumber( limit, fallback ) );
+}

package/lib/redirectTarget.js

@@ -1,3 +1,5 @@
+import { servableUrl } from "./href.js";
+
 /**
  * Returns true for absolute URLs (any scheme, e.g. "https://", "mailto:") and
  * protocol-relative URLs ("//cdn.example.com").  These must be redirected
@@ -22,10 +24,9 @@ export function isExternalUrl( value ) {
  * `file_server` web server — for that exact path. A clean leaf URL maps to no
  * file there and 404s.
  *
- * Appending `.html` to leaf paths (while leaving trailing-slash folder URLs to
- * the server's `index.html` rule) yields a path that maps to a real file on any
- * static server. Absolute/external URLs, query strings and fragments are left
- * untouched.
+ * Naming the file itself yields a path every static server answers directly, and
+ * one that matches the links the rest of the site carries. Absolute/external URLs
+ * are left untouched, and a query string or fragment stays at the end.
  *
  * @param {string} target site-relative path or absolute URL
  * @returns {string} a path/URL a plain static server can serve directly
@@ -35,12 +36,5 @@ export function servableRedirectTarget( target ) {
 
 	if ( isExternalUrl( target ) ) return target;
 
-	// Split off any query string / fragment so the extension lands on the path.
-	const [ , path, suffix ] = /^([^?#]*)([?#].*)?$/.exec( target );
-
-	// Folder URLs ("/de/jobs/") rely on the server's index.html rule; paths that
-	// already carry the ".html" extension are served as-is.
-	if ( path === "" || path.endsWith( "/" ) || path.endsWith( ".html" ) ) return path + ( suffix ?? "" );
-
-	return path + ".html" + ( suffix ?? "" );
+	return servableUrl( target );
 }

package/lib/sectionManifest.js

@@ -95,7 +95,7 @@ export const BUILTIN_SECTIONS = {
 			limit: {
 				type: "number",
 				label: "Number of entries",
-				hint: "0 lists every page found.",
+				hint: "0 lists every page found. Left unset on a list with entries per page, every page found is paged through.",
 				default: 5,
 			},
 			offset: {
@@ -126,8 +126,20 @@ export const BUILTIN_SECTIONS = {
 			"date-style": {
 				type: "enum",
 				label: "Date format",
-				values: [ "short", "medium", "long", "full" ],
+				values: [ "short", "medium", "long", "full", "iso" ],
 				default: "long",
+				hint: "\"iso\" writes 2020-10-20 in every language; the others follow the page's language.",
+			},
+			"time-style": {
+				type: "enum",
+				label: "Time format",
+				values: [ "short", "medium", "long", "full", "iso" ],
+				hint: "Left unset, entries show their date only. \"iso\" writes 12:16.",
+			},
+			timezone: {
+				type: "text",
+				label: "Time zone",
+				hint: "Zone the dates are read in, e.g. Europe/Berlin. Defaults to UTC, which is what a date without a time of day should be shown in.",
 			},
 			"heading-level": {
 				type: "number",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "scavold",
-	"version": "0.2.0-rc.4",
+	"version": "0.2.0-rc.5",
 	"type": "module",
 	"description": "VitePress theme framework — a scaffold for building custom VitePress themes with Vue at the core",
 	"keywords": [

package/scripts/check-fixture.js

@@ -218,9 +218,32 @@ expect( backgrounds.length === 2 && backgrounds.every( t => /autoplay/.test( t )
 
 // ── page list ────────────────────────────────────────────────────────────────
 
+console.log( "\nnavigation" );
+
+const blogPage = built( join( "blog", "index.html" ) );
+const menu = ( blogPage.match( /<nav aria-label="Main navigation"[\s\S]*?<\/nav>/ ) ?? [""] )[0];
+const crumbs = ( blogPage.match( /<nav class="breadcrumb"[\s\S]*?<\/nav>/ ) ?? [""] )[0];
+
+// Every link names the file that answers it, so a static server hits it on its
+// first attempt and the sitemap can name the very same URL.
+expect( menu.includes( '<a href="/index.html">Home</a>' ),
+	"links the site's own index page as the file it is built into" );
+expect( menu.includes( '<a href="/blog/index.html"' ),
+	"links a folder's index page as that file, not as the folder" );
+expect( menu.includes( '<a href="/containers.html">' ),
+	"links a plain page as its own file" );
+expect( crumbs.includes( '<a href="/blog/index.html"' ) && crumbs.includes( 'aria-current="page"' ),
+	"marks the page the breadcrumb ends on" );
+
+const sitemap = built( "sitemap.xml" );
+
+expect( sitemap.includes( "<loc>https://fixture.example.com/index.html</loc>" ) &&
+	sitemap.includes( "<loc>https://fixture.example.com/blog/index.html</loc>" ),
+"lists in the sitemap the same URLs the pages link to" );
+
 console.log( "\npage list" );
 
-const blog = built( join( "blog", "index.html" ) );
+const blog = blogPage;
 const lists = blog.split( '<ul class="scavold-pagelist__items"' );
 const dated = lists[1] ?? "";
 const titled = lists[2] ?? "";
@@ -269,6 +292,10 @@ const paged = lists[3] ?? "";
 
 expect( entryTitles( paged ).length === 2, "renders one page worth of entries, not the whole list",
 	`found ${entryTitles( paged ).length}` );
+// The list names no limit: one that paginates reaches every page it found, or the
+// pager would turn the pages of a five-entry selection.
+expect( /<time class="scavold-pagelist__date" datetime="2026-06-21T00:00:00\.000Z">2026-06-21 02:00</.test( paged ),
+	"writes dates in the style and the zone the list asked for" );
 expect( /<nav class="scavold-pagelist__pager" aria-label="[^"]+"/.test( blog ),
 	"gives the pager a landmark a screen reader can announce" );
 expect( /<p class="scavold-pagelist__status" role="status">[^<]*1[^<]*2<\/p>/.test( blog ),
@@ -278,6 +305,22 @@ expect( /<button[^>]*class="[^"]*\bcurrent\b[^"]*scavold-pagelist__page[^"]*"[^>
 expect( /scavold-pagelist__page--previous[^>]*disabled|disabled[^>]*scavold-pagelist__page--previous/.test( blog ),
 	"offers no step back from the first page" );
 
+// A theme is not confined to restyling what Scavold renders: the fixture maps a
+// container to a component of its own, which reuses the very same selection and
+// formatting through the exported composable.
+const ownList = ( blog.match( /<ol class="site-postlist"[\s\S]*?<\/ol>/ ) ?? [""] )[0];
+
+expect( ownList.includes( ">Newest post<" ) && ownList.includes( ">Middle post<" ),
+	"lets a site's own component render a page list, selection and order included" );
+// The weekday and the month name are what tell "full" apart from the other styles.
+// Their arrangement and punctuation are not asserted: those follow the locale data of
+// whichever runtime builds the site, and differ between one Bun release and the next.
+const ownDate = ( ownList.match( /<time[^>]*class="site-postlist__date"[^>]*>([^<]*)</ ) ?? [ "", "" ] )[1].trim();
+
+expect( [ "Sunday", "21", "June", "2026" ].every( part => ownDate.includes( part ) ),
+	"hands a site's own component the timestamp formatting as well",
+	`the entry reads ${JSON.stringify( ownDate )}` );
+
 // ── content security policy ──────────────────────────────────────────────────
 
 console.log( "\ncontent security policy" );
@@ -303,7 +346,7 @@ expect( feed.startsWith( '<?xml version="1.0" encoding="UTF-8"?>' ), "writes a f
 expect( /<atom:link href="https:\/\/fixture\.example\.com\/feed\.xml"/.test( feed ),
 	"points the feed at itself, absolutely" );
 expect( feedItems.length === 3, "honours the limit the site set", `found ${feedItems.length} entries, expected 3` );
-expect( /<link>https:\/\/fixture\.example\.com\/blog\/draft<\/link>/.test( feedItems[0] ?? "" ),
+expect( /<link>https:\/\/fixture\.example\.com\/blog\/draft\.html<\/link>/.test( feedItems[0] ?? "" ),
 	"leads with the newest announced post and links it absolutely" );
 expect( /<pubDate>[A-Z][a-z]{2}, \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT<\/pubDate>/.test( feed ),
 	"dates entries the way a reader expects" );