scavold 0.2.1 → 0.5.0

package/CHANGELOG.md

@@ -9,6 +9,83 @@ one offered; a patch release does not.
 
 ## [Unreleased]
 
+## [0.5.0] — 2026-10-04
+
+### Added
+
+- A `group` container: content held together only to arrange it — an image with the
+  paragraph flowing around it, say — without claiming a meaning, rendered as a `<div>`.
+  It offers the same layouts as a section, for where no sectioning element fits.
+
+### Changed
+
+- The option of `details` that makes blocks close each other is called "Accordion" in
+  the editor ("Akkordeon" in German), so it is not mistaken for the new group. It is
+  still written `group=` in Markdown.
+
+## [0.4.0] — 2026-10-04
+
+### Added
+
+- Layout variants for `section`, `article` and `aside`: `layout=float-left` or
+  `float-right` lets the content flow around the first block, an image usually;
+  `split-left` or `split-right` sets block and content side by side. The editor offers
+  them as buttons with icons Scavold brings along, drawn after Font Awesome's solid
+  style; a site replaces one by keeping an icon of the same name in `.cratly/icons/`.
+- The section kinds Scavold brings are described to the editor in English and German —
+  their names, hints and the choices of their options — so a German editor no longer
+  reads "Preload" or "metadata". A site's `.cratly.config.yaml` may give labels and
+  hints in several languages the same way, as a map of locale → text.
+- Each section kind Scavold brings explains itself where the editor offers the types to
+  choose from, and links its description on a new page for authors at scavold.io — the
+  first of the documentation in German as well as English. A site's own containers do
+  the same with `hint` and `docs` in `.cratly.config.yaml`.
+
+### Changed
+
+- The section-type manifest carries the texts of the built-in section kinds as maps of
+  locale → text, and their `docs` as maps of locale → address. A cratly editor deployed
+  before these were supported shows such a text as "[object Object]": update the editor
+  before a site moves to this version.
+
+## [0.3.0] — 2026-10-04
+
+Tagged, not published to npm; its changes reach sites with 0.4.0.
+
+### Added
+
+- A `card` container: a unit of its own, such as an image, a heading and a few lines.
+  `link` names a page and makes the whole card clickable, its "Read more" naming the
+  page for screen readers; links written into the card stay clickable.
+- A `details` container: content collapsed under a title (`summary`) until the reader
+  expands it, rendered as a native `<details>`. `open` starts it expanded, and blocks
+  sharing a `group` close each other, so only one of them is open at a time.
+- A `grid` container: the blocks written inside it side by side, at most `columns` (2,
+  3 or 4) in a row, continuing in the next. A cell never gets narrower than
+  `--scavold-grid-min`, so a narrow screen drops columns by itself without breakpoints.
+  A theme declares the `sizes` of images in a grid by column count through
+  `enhanceApp( context, { gridImageSizes } )`.
+- `provideImageSizes()`: a layout component gives the images inside it a `sizes`
+  value, replacing the site's default but not a per-image override.
+- Image captions. The title of a Markdown image is its caption: an image standing alone
+  in its paragraph becomes a `<figure>` with a `<figcaption>`, one amid text shows it as
+  its tooltip. A grid of captioned images makes a gallery.
+- Icons for section controls. A `boolean` prop and the choices of an `enum` prop in
+  `.cratly.config.yaml` may name an `icon`, kept as `.cratly/icons/<name>.svg` in the
+  site. The section-type manifest embeds the icons it refers to, so the cratly editor
+  can offer a toggle button or a group of buttons instead of a checkbox or a select. A
+  reference to a missing icon is reported during the build.
+
+### Changed
+
+- The title of a Markdown image is shown: below an image standing alone, as its tooltip
+  amid text. A site that used image titles for something else will see them now.
+
+### Fixed
+
+- A `sizes=` override in an image title no longer shows up as a tooltip
+  ("sizes=100vw") on the published image.
+
 ## [0.2.1] — 2026-10-04
 
 ### Fixed
@@ -369,7 +446,10 @@ 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.
 
-[Unreleased]: https://gitlab.com/cratly/scavold/-/compare/v0.2.1...main
+[Unreleased]: https://gitlab.com/cratly/scavold/-/compare/v0.5.0...main
+[0.5.0]: https://gitlab.com/cratly/scavold/-/compare/v0.4.0...v0.5.0
+[0.4.0]: https://gitlab.com/cratly/scavold/-/compare/v0.3.0...v0.4.0
+[0.3.0]: https://gitlab.com/cratly/scavold/-/compare/v0.2.1...v0.3.0
 [0.2.1]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0...v0.2.1
 [0.2.0]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.12...v0.2.0
 [0.2.0-rc.12]: https://gitlab.com/cratly/scavold/-/compare/v0.2.0-rc.11...v0.2.0-rc.12

package/COMPONENTS.md

@@ -69,6 +69,48 @@ A folder on the way that has no `index.md` is named as text, a `<span>` in place
 
 ---
 
+### `<ScavoldCard>`
+
+A unit of its own — an image, a heading and a few lines, say — set apart from the text
+around it. Cards side by side go into a [grid](#scavoldgrid):
+
+```markdown
+:::: grid columns=3
+::: card link=about/team.md
+![Our team at the pond](/team.jpg)
+
+### Who we are
+
+Twelve people, one pond.
+:::
+::::
+```
+
+| Argument | Type | Description |
+|---|---|---|
+| `link` | `page-ref` | Page the card links to. Makes the whole card clickable; a reference to a page that does not exist leaves the card unlinked. |
+
+```html
+<div class="scavold-card scavold-card--linked">
+  …
+  <a class="scavold-card__link" href="/about/team.html" aria-label="Read more: Team">Read more</a>
+</div>
+```
+
+The link's text is the same on every card, translated; its accessible name adds the
+title of the page it leads to, so a list of links read out by a screen reader tells the
+cards apart. Its click area is stretched over the whole card, while links written into
+the card stay clickable on top.
+
+Scavold styles only what keeps a card working: images stay within it, and the link
+covers it. Its frame, padding and where its image sits are the theme's, through
+`scavold-card` and `scavold-card--linked`.
+
+Register a component under the name `ScavoldCard` before calling `scavoldEnhanceApp` to
+render it differently, and resolve the arguments with [`useCard`](#usecard-props).
+
+---
+
 ### `<ScavoldContainer>`
 
 Fallback component for Markdown container blocks whose name has no dedicated
@@ -92,6 +134,11 @@ component for each container name they declare in `.cratly.config.yaml`.
 
 See [`useContainer`](#usecontainer-props) for building custom container components.
 
+`:::group` is a built-in mapped to it: content held together only to arrange it, with no
+meaning of its own, rendered as `<div class="group">`. It offers the same
+[layout](#layout) as a section. Use it where no sectioning element fits — HTML keeps
+`<div>` for exactly that.
+
 ---
 
 ### `<ScavoldCover>`
@@ -249,6 +296,94 @@ not promise.
 
 ---
 
+### `<ScavoldDetails>`
+
+Content collapsed under a title until the reader expands it. Written as a container
+block and rendered as a native `<details>` element, so keyboard operation, the expanded
+state for screen readers and revealing the content on find in page come with it.
+
+```markdown
+::: details summary="Opening hours" group=faq
+Monday to Friday, 9 am to 5 pm.
+:::
+```
+
+| Argument | Type | Description |
+|---|---|---|
+| `summary` | `string` | Title, always visible; clicking it expands or collapses the content. Left out, a translated "Details" stands in. |
+| `open` | flag | Starts expanded. |
+| `group` | `string` | Blocks with the same group close each other, so only one is expanded at a time. Rendered as the `name` attribute of `<details>`. |
+
+```html
+<details class="scavold-details" name="faq">
+  <summary class="scavold-details__summary">Opening hours</summary>
+  <div class="scavold-details__content">…</div>
+</details>
+```
+
+Scavold adds no styles of its own; the browser's disclosure marker stays until a theme
+replaces it. Register a component under the name `ScavoldDetails` before calling
+`scavoldEnhanceApp` to render it differently, and resolve the arguments with
+[`useDetails`](#usedetails-props).
+
+---
+
+### `<ScavoldGrid>`
+
+Puts the blocks written inside it side by side, at most `columns` of them in a row; a
+full row continues in the next. Each block is one cell — a paragraph, an image, or an
+embedded container, which is how several blocks share a cell:
+
+```markdown
+:::: grid columns=3
+![Pond in spring](/pond.jpg)
+
+![Meadow](/meadow.jpg)
+
+::: section
+### Opening hours
+Monday to Friday.
+:::
+::::
+```
+
+The grid needs the longer fence when it contains a container; the cratly editor writes
+it that way by itself.
+
+| Argument | Type | Description |
+|---|---|---|
+| `columns` | `2` \| `3` \| `4` | Most cells side by side. Defaults to `2`. |
+
+```html
+<div class="scavold-grid scavold-grid--3" style="--scavold-grid-columns: 3">…</div>
+```
+
+A cell never gets narrower than `--scavold-grid-min` (default `14rem`), so on a narrow
+screen the grid drops columns by itself, down to one, without breakpoints. Themes set
+that variable and `--scavold-grid-gap` (default `1.5rem`), or replace the layout
+through the `scavold-grid--<columns>` class. Margins of the cells themselves —
+including the indent browsers give a `<figure>` — are removed; the gap spaces them.
+
+Images in a grid take the `sizes` the theme declares for its column count, since only
+the theme knows how wide a cell is at which screen width. A column count it leaves out
+keeps the site's `image_sizes` of `.cratly.config.yaml` for its images: sharp in every column, but on a wide screen
+a larger variant than a cell needs. An image with a `sizes=` override of its own keeps
+it, and images nested deeper — in a card in a cell — take the grid's value as well.
+
+```js
+// .vitepress/theme/index.js — cells 22rem wide in a 72rem column, two columns from 48rem
+await scavoldEnhanceApp( context, {
+    gridImageSizes: {
+        3: "(min-width: 72rem) 22rem, (min-width: 48rem) 50vw, 100vw",
+    },
+} );
+```
+
+Register a component under the name `ScavoldGrid` before calling `scavoldEnhanceApp`
+to render it differently, and resolve the arguments with [`useGrid`](#usegrid-props).
+
+---
+
 ### `<ScavoldImage>`
 
 Renders a responsive `<picture>` element for local images. Not intended for direct
@@ -264,6 +399,7 @@ frontmatter field can use it directly.
 | `srcset` | `string` | `""` | `srcset` string for the original format (JPEG/PNG) |
 | `webp-srcset` | `string` | `""` | `srcset` string for the WebP variants |
 | `sizes` | `string` | `"100vw"` | CSS `sizes` attribute applied to all sources |
+| `sizes-fallback` | `boolean` | `false` | Marks `sizes` as the site's default only, which a layout around the image may replace (see [`provideImageSizes`](#useimagesizes--provideimagesizes-sizes)). Set by the Markdown renderer. |
 | `alt` | `string` | `""` | Alt text for the `<img>` element |
 | `loading` | `string` | `"lazy"` | `loading` attribute of the `<img>`; `"eager"` for an image at the top of a page |
 | `fetchpriority` | `string` | — | `fetchpriority` attribute of the `<img>`, e.g. `"high"` for the largest image above the fold |
@@ -278,6 +414,30 @@ frontmatter field can use it directly.
 </picture>
 ```
 
+#### Captions
+
+The title of a Markdown image is its caption. An image standing alone in its paragraph
+is rendered as a figure with the caption below it; amid text, where no figure fits, the
+caption is the image's tooltip. A `sizes=` override in the title is taken out first and
+never reaches the page:
+
+```markdown
+![Pond with water lilies](/pond.jpg "The pond in spring")
+![Pond with water lilies](/pond.jpg "sizes=100vw The pond in spring")
+```
+
+```html
+<figure class="scavold-figure">
+  <picture>…</picture>
+  <figcaption class="scavold-figure__caption">The pond in spring</figcaption>
+</figure>
+```
+
+The alt text says what the image shows, for those who cannot see it; the caption adds
+to it for everyone. Scavold adds no styles to a figure, so the indent browsers give
+`<figure>` stays until a theme sets its own margins. A [grid](#scavoldgrid) of
+captioned images is a gallery.
+
 ---
 
 ### `<ScavoldLayout>`
@@ -834,6 +994,36 @@ async function enhanceApp( context ) {
 }
 ```
 
+#### Layout
+
+`section`, `article` and `aside`, and the generic `group`, take a `layout` arranging their
+first block — an image, usually — and the content after it. Left out, the block stands
+above the content.
+
+```markdown
+::: section layout=float-left
+![The pond in spring](/pond.jpg)
+
+Text flowing around the image, and on below it.
+:::
+```
+
+| `layout` | Arrangement |
+|---|---|
+| `float-left`, `float-right` | The content flows around the block and on below it. |
+| `split-left`, `split-right` | Block and content side by side; the content does not run below the block. |
+
+The element carries the choice as `data-layout`, and `scavold/styles/layouts.css`, which
+`enhanceApp` brings along, implements it. A section narrower than 30rem stacks its block
+above the content again, whatever its layout. Themes set the block's width through
+`--scavold-layout-width` (default `40%`) and the space beside and below it through
+`--scavold-layout-gap` (default `1.5rem`), or replace the rules.
+
+The cratly editor offers the choices as buttons with Scavold's own icons, drawn after
+Font Awesome's solid style. A site replaces one by keeping an icon of the same name —
+`stacked`, `float-left`, `float-right`, `split-left`, `split-right` — in its
+`.cratly/icons/`.
+
 ---
 
 ## Composables
@@ -884,6 +1074,24 @@ Leave the `autoplay` attribute off the element; it would start the video regardl
 
 ---
 
+### `useCard( props )`
+
+```js
+import { useCard, cardProps } from "scavold/composables/useCard.js";
+```
+
+Resolves the arguments of a `:::card` block for a site's own card component:
+
+```js
+const props = defineProps( { ...cardProps } );
+const { href, title } = useCard( props );
+```
+
+`href` is the URL of the linked page and `title` its title, both empty when the card
+links nowhere or to a page that does not exist.
+
+---
+
 ### `useContainer( props )`
 
 ```js
@@ -988,6 +1196,41 @@ are exported as well.
 
 ---
 
+### `useDetails( props )`
+
+```js
+import { useDetails, detailsProps } from "scavold/composables/useDetails.js";
+```
+
+Resolves the arguments of a `:::details` block for a site's own details component:
+
+```js
+const props = defineProps( { ...detailsProps } );
+const { summary, open, group } = useDetails( props );
+```
+
+`summary` is the trimmed title or an empty string, `open` a boolean, and `group` the
+group name or `undefined`.
+
+---
+
+### `useGrid( props )`
+
+```js
+import { useGrid, gridProps, GRID_COLUMNS } from "scavold/composables/useGrid.js";
+```
+
+Resolves the arguments of a `:::grid` block for a site's own grid component:
+
+```js
+const props = defineProps( { ...gridProps } );
+const { columns } = useGrid( props );
+```
+
+`columns` is one of `GRID_COLUMNS` (`2`, `3`, `4`), falling back to the first.
+
+---
+
 ### `useHierarchy()`
 
 ```js
@@ -1070,6 +1313,29 @@ const items = computed( () =>
 
 ---
 
+### `useImageSizes()` / `provideImageSizes( sizes )`
+
+```js
+import { provideImageSizes, useImageSizes } from "scavold/composables/useImageSizes.js";
+```
+
+A layout component that knows how wide it draws its content provides a `sizes` value
+for the images inside it — a string or a ref:
+
+```js
+// SiteSidebar.vue — content 18rem wide from 64rem, full width below
+provideImageSizes( "(min-width: 64rem) 18rem, 100vw" );
+```
+
+Every `<ScavoldImage>` inside that carries only the site's default takes this value
+instead; one with a `sizes=` override, or given its `sizes` by a component like the
+cover, keeps its own. An empty value leaves the images with what the layout around
+provides. The value is resolved while rendering, so it is in the markup the server
+sends. `useImageSizes()` reads it, for a component rendering images of its own;
+`<ScavoldGrid>` provides one from `gridImageSizes`.
+
+---
+
 ### `usePageList( props )`
 
 ```js
@@ -1323,6 +1589,9 @@ reserved), loses browser preload scanning (images load later), and produces a fl
 of empty space on every navigation during hydration. The `sizes` + `srcset` approach
 was specifically designed to avoid all of these.
 
+A layout wrapping Markdown content rather than rendering images itself — a sidebar, a
+grid — reaches the images inside through [`provideImageSizes`](#useimagesizes--provideimagesizes-sizes).
+
 The global `image_sizes` in `.cratly.config.yaml` is a fallback for images that have
 no layout-aware component wrapping them. Set it to the most common case in the
 theme (typically the prose column width) and override via dedicated components for

package/components/ScavoldCard.vue

@@ -0,0 +1,51 @@
+<script setup>
+import { computed } from "vue";
+import { useCard, cardProps } from "../composables/useCard.js";
+import { useScavoldI18n } from "../composables/useI18n.js";
+
+const props = defineProps( cardProps );
+
+const { href, title } = useCard( props );
+
+const { t } = useScavoldI18n();
+const more = t( "card.more" );
+
+// The visible text is the same on every card; the accessible name says where each
+// one leads, starting with the visible text as WCAG 2.5.3 asks.
+const linkLabel = computed( () => ( title.value ? `${more.value}: ${title.value}` : more.value ) );
+</script>
+
+<template>
+  <div class="scavold-card" :class="[ props.class, { 'scavold-card--linked': href } ]">
+    <slot />
+    <a v-if="href" class="scavold-card__link" :href="href" :aria-label="linkLabel">{{ more }}</a>
+  </div>
+</template>
+
+<style scoped>
+/*
+ * Functional only: how a card looks — its frame, its padding, where its image sits —
+ * is the theme's. What is set here keeps it working: images stay within the card,
+ * and the link of a linked card covers all of it, so the whole card can be clicked.
+ * Links written into the card stay clickable on top of that.
+ */
+.scavold-card :deep(img) {
+	max-width: 100%;
+	height: auto;
+}
+
+.scavold-card--linked {
+	position: relative;
+}
+
+.scavold-card__link::after {
+	content: "";
+	position: absolute;
+	inset: 0;
+}
+
+.scavold-card--linked :deep(a:not(.scavold-card__link)) {
+	position: relative;
+	z-index: 1;
+}
+</style>

package/components/ScavoldDetails.vue

@@ -0,0 +1,23 @@
+<script setup>
+import { useDetails, detailsProps } from "../composables/useDetails.js";
+import { useScavoldI18n } from "../composables/useI18n.js";
+
+const props = defineProps( detailsProps );
+
+const { summary, open, group } = useDetails( props );
+
+const { t } = useScavoldI18n();
+const fallbackSummary = t( "details.summary" );
+</script>
+
+<template>
+  <!-- Native <details>: keyboard operation, the expanded state for screen readers and
+       revealing the content on find in page come with the element. `name` makes
+       blocks sharing a group close each other. -->
+  <details class="scavold-details" :class="props.class" :open="open" :name="group">
+    <summary class="scavold-details__summary">{{ summary || fallbackSummary }}</summary>
+    <div class="scavold-details__content">
+      <slot />
+    </div>
+  </details>
+</template>

package/components/ScavoldGrid.vue

@@ -0,0 +1,53 @@
+<script setup>
+import { computed, inject } from "vue";
+import { useGrid, gridProps } from "../composables/useGrid.js";
+import { GRID_IMAGE_SIZES, provideImageSizes } from "../composables/useImageSizes.js";
+
+const props = defineProps( gridProps );
+
+const { columns } = useGrid( props );
+
+// The theme knows how wide a cell is at which screen width; without a value for this
+// column count, images keep what applies around the grid.
+const imageSizes = inject( GRID_IMAGE_SIZES, {} );
+provideImageSizes( computed( () => imageSizes[columns.value] ?? "" ) );
+
+const style = computed( () => ( { "--scavold-grid-columns": columns.value } ) );
+</script>
+
+<template>
+  <div class="scavold-grid" :class="[ props.class, `scavold-grid--${columns}` ]" :style="style">
+    <slot />
+  </div>
+</template>
+
+<style scoped>
+/*
+ * Functional layout: every block written in the grid is a cell, at most
+ * --scavold-grid-columns of them side by side. A cell never gets narrower than
+ * --scavold-grid-min, so on a narrow screen the grid drops columns by itself,
+ * down to one, without breakpoints. Themes adjust both variables and the gap, or
+ * replace the rule entirely.
+ */
+.scavold-grid {
+	--_gap: var(--scavold-grid-gap, 1.5rem);
+	--_min: var(--scavold-grid-min, 14rem);
+	--_fraction: calc((100% - (var(--scavold-grid-columns) - 1) * var(--_gap)) / var(--scavold-grid-columns));
+
+	display: grid;
+	gap: var(--_gap);
+	grid-template-columns: repeat(auto-fill, minmax(min(100%, max(var(--_min), var(--_fraction))), 1fr));
+}
+
+/* The gap spaces the cells; margins of their own would only put them out of line. */
+.scavold-grid > :slotted(*) {
+	min-width: 0;
+	margin: 0;
+}
+
+/* An image never reaches into the next cell, whatever the theme does elsewhere. */
+.scavold-grid :deep(img) {
+	max-width: 100%;
+	height: auto;
+}
+</style>

package/components/ScavoldImage.vue

@@ -1,14 +1,23 @@
 <script setup>
-defineProps( {
+import { computed } from "vue";
+import { useImageSizes } from "../composables/useImageSizes.js";
+
+const props = defineProps( {
 	src: { type: String, required: true },
 	srcset: { type: String, default: "" },
 	webpSrcset: { type: String, default: "" },
 	sizes: { type: String, default: "100vw" },
+	// Set by the Markdown renderer when `sizes` is only the site's default, which a
+	// layout around the image may replace with a better fit (see useImageSizes).
+	sizesFallback: { type: Boolean, default: false },
 	alt: { type: String, default: "" },
 	// An image above the fold — a cover — is wanted at once, not when it scrolls into view.
 	loading: { type: String, default: "lazy" },
 	fetchpriority: { type: String, default: undefined },
 } );
+
+const provided = useImageSizes();
+const effectiveSizes = computed( () => ( props.sizesFallback && provided.value ) || props.sizes );
 </script>
 
 <template>
@@ -17,18 +26,18 @@ defineProps( {
       v-if="webpSrcset"
       type="image/webp"
       :srcset="webpSrcset"
-      :sizes="sizes"
+      :sizes="effectiveSizes"
     />
     <source
       v-if="srcset"
       :srcset="srcset"
-      :sizes="sizes"
+      :sizes="effectiveSizes"
     />
     <img
       :src="src"
       :alt="alt"
       :role="alt ? undefined : 'presentation'"
-      :sizes="sizes"
+      :sizes="effectiveSizes"
       :loading="loading"
       :fetchpriority="fetchpriority"
       decoding="async"

package/composables/useCard.js

@@ -0,0 +1,45 @@
+import { computed } from "vue";
+import { containerProps } from "./useContainer.js";
+import { useHierarchy } from "./hierarchy";
+
+/**
+ * Props definition for card container components. Spread into `defineProps`
+ * alongside any component-specific props.
+ */
+export const cardProps = {
+	...containerProps,
+
+	/** Page the card links to, as a path in the pages folder. */
+	dataLink: { type: String, default: null },
+};
+
+/**
+ * Composable for card container components.
+ *
+ * Parses the props emitted by the markdown-it container renderer for a
+ * `:::card` block and exposes derived values ready for binding:
+ *
+ *   - `href`  — URL of the linked page, or an empty string when the card links
+ *               nowhere or to a page that does not exist
+ *   - `title` — title of the linked page, or an empty string
+ *
+ * Custom card components should call this composable so they share identical
+ * attribute resolution without duplicating the logic.
+ *
+ * @param {object} props  reactive props from defineProps
+ * @returns {{ href, title }}
+ */
+export function useCard( props ) {
+	const { resolveByPath, nodeHref, nodeTitle } = useHierarchy();
+
+	const target = computed( () => {
+		const path = props.dataLink?.trim();
+
+		return path ? resolveByPath( path ) : undefined;
+	} );
+
+	const href = computed( () => ( target.value ? nodeHref( target.value ) : "" ) );
+	const title = computed( () => ( target.value ? nodeTitle( target.value ) : "" ) );
+
+	return { href, title };
+}