scavold 0.2.0 → 0.4.0

package/lib/sectionManifest.js

@@ -1,6 +1,7 @@
 import { join } from "node:path";
-import { mkdir, writeFile, readFile } from "node:fs/promises";
-import { SECTIONING_ELEMENTS } from "./containers.js";
+import { fileURLToPath } from "node:url";
+import { mkdir, writeFile, readFile, readdir } from "node:fs/promises";
+import { GRID_COLUMNS, SECTIONING_ELEMENTS } from "./containers.js";
 
 /**
  * Canonical URL of the section-type grammar this manifest conforms to. The
@@ -15,188 +16,479 @@ export const SECTION_SPEC_VERSION = 0;
 export const SECTION_MANIFEST_DIR = ".cratly";
 export const SECTION_MANIFEST_FILE = "sections.json";
 
+/**
+ * The one folder a site keeps the icons of its section controls in, one SVG file
+ * each, named by the file's base name. See ADR 0010 on cratly.io for why there is
+ * no other place an icon can come from.
+ */
+export const ICON_DIR = "icons";
+
+/** Names an icon may have: a base name, never a path. Mirrors the grammar's `iconName`. */
+const ICON_NAME = /^[a-z0-9][a-z0-9-]*$/;
+
+/**
+ * A text for the editor, in English as the fallback and in German. Further languages
+ * are further keys; see "Localized texts" on https://cratly.io/reference/section-types.
+ *
+ * @param {string} en
+ * @param {string} de
+ * @returns {{"*": string, de: string}}
+ */
+function text( en, de ) {
+	return { "*": en, de };
+}
+
+/**
+ * The choice of one value among several, each with a label.
+ *
+ * @param {...[string, string, string]} entries value, English and German label of each
+ * @returns {Array<{value: string, label: object}>}
+ */
+function choices( ...entries ) {
+	return entries.map( ( [ value, en, de ] ) => ( { value, label: text( en, de ) } ) );
+}
+
+/**
+ * Pages explaining the section kinds to authors, in English and German, linked by the
+ * editor beside their hints. Both carry the same anchor per kind; header, footer, main
+ * and nav share one.
+ */
+const AUTHOR_DOCS = {
+	"*": "https://scavold.io/authors/sections.html",
+	de: "https://scavold.io/de/authors/sections.html",
+};
+
+/**
+ * @param {string} anchor id of the kind's heading on the pages for authors
+ * @returns {{"*": string, de: string}}
+ */
+function docs( anchor ) {
+	return Object.fromEntries( Object.entries( AUTHOR_DOCS ).map( ( [ locale, page ] ) => [ locale, `${page}#${anchor}` ] ) );
+}
+
+/** Names of the sectioning wrappers in the editor. */
+const SECTIONING_LABELS = {
+	article: text( "Article", "Artikel" ),
+	aside: text( "Aside", "Randbereich" ),
+	footer: text( "Footer", "Fußbereich" ),
+	header: text( "Header", "Kopfbereich" ),
+	main: text( "Main", "Hauptinhalt" ),
+	nav: text( "Nav", "Navigation" ),
+	section: text( "Section", "Abschnitt" ),
+};
+
+/** What each sectioning wrapper is for, in the editor's type picker. */
+const SECTIONING_HINTS = {
+	article: text(
+		"A piece that stands on its own — a post, a news item — and would make sense elsewhere too.",
+		"Ein Beitrag, der für sich steht – ein Artikel, eine Meldung – und auch anderswo verständlich wäre.",
+	),
+	aside: text(
+		"Content beside the main text — a note, a box of related links — that it could do without.",
+		"Inhalt neben dem eigentlichen Text – ein Hinweis, eine Box mit Links –, auf den er auch verzichten könnte.",
+	),
+	footer: text(
+		"Closing information of the page or of the section around it, like an author or related links.",
+		"Abschließende Angaben zur Seite oder zum umgebenden Abschnitt, etwa Autor oder weiterführende Links.",
+	),
+	header: text(
+		"Introductory content of the page or of the section around it, like a title with a lead.",
+		"Einleitender Inhalt der Seite oder des umgebenden Abschnitts, etwa Titel mit Vorspann.",
+	),
+	main: text(
+		"The page's main content. A page has one at most, and the site's design usually provides it already.",
+		"Der Hauptinhalt der Seite. Eine Seite hat höchstens einen, und meist stellt ihn die Gestaltung schon bereit.",
+	),
+	nav: text(
+		"A group of links for finding one's way, like a table of contents.",
+		"Eine Gruppe von Links zur Orientierung, etwa ein Inhaltsverzeichnis.",
+	),
+	section: text(
+		"A part of the page with a topic of its own, usually opened by a heading.",
+		"Ein Teil der Seite mit eigenem Thema, meist mit einer Überschrift am Anfang.",
+	),
+};
+
+/**
+ * Sectioning wrappers offering a layout of their first block — an image, usually —
+ * and the text after it. The variants are implemented in styles/layouts.css.
+ */
+const LAYOUT_SECTIONS = new Set( [ "section", "article", "aside" ] );
+
+const LAYOUT_PROP = {
+	type: "enum",
+	label: text( "Layout", "Anordnung" ),
+	hint: text(
+		"How the first block — an image, say — and the text after it are arranged. Left unset, the block stands above the text.",
+		"Wie der erste Block – etwa ein Bild – und der Text danach angeordnet sind. Ohne Angabe steht der Block über dem Text.",
+	),
+	// shown for the choice of no layout, which stacks the block above the text
+	icon: "stacked",
+	values: [
+		{ value: "float-left", label: text( "Text flowing around it, block on the left", "Text umfließt, Block links" ), icon: "float-left" },
+		{ value: "float-right", label: text( "Text flowing around it, block on the right", "Text umfließt, Block rechts" ), icon: "float-right" },
+		{ value: "split-left", label: text( "Side by side, block on the left", "Nebeneinander, Block links" ), icon: "split-left" },
+		{ value: "split-right", label: text( "Side by side, block on the right", "Nebeneinander, Block rechts" ), icon: "split-right" },
+	],
+};
+
 /**
  * Editor-facing schema for Scavold's built-in section kinds. Emitted into each
  * website's `.cratly/sections.json` so the cratly editor can render the right
- * controls when an author inserts or edits a section.
+ * controls when an author inserts or edits a section. Every text comes in English
+ * and German; a test keeps both complete.
  *
  * Keep the `video` props in sync with `videoProps` in
  * composables/useVideo.js — that composable defines the runtime (data-*) props;
  * this object describes the same options in the editor's typed vocabulary. The
- * same goes for `cover` and `coverProps` in composables/useCover.js.
+ * same goes for `cover` and `coverProps` in composables/useCover.js, for
+ * `details` and `detailsProps` in composables/useDetails.js, for `grid` and
+ * `gridProps` in composables/useGrid.js, and for `card` and `cardProps` in
+ * composables/useCard.js.
  */
 export const BUILTIN_SECTIONS = {
-	// The seven sectioning wrappers are generic content containers with no
-	// named props of their own; authors may still add ad-hoc flags / key-value
-	// arguments, which the editor surfaces only when declared in config.
+	// The seven sectioning wrappers are generic content containers; authors may
+	// still add ad-hoc flags / key-value arguments, which the editor surfaces only
+	// when declared in config. Those holding running content offer a layout.
 	...Object.fromEntries(
 		[...SECTIONING_ELEMENTS].map( name => [ name, {
-			label: name[0].toUpperCase() + name.slice( 1 ),
+			label: SECTIONING_LABELS[name],
+			hint: SECTIONING_HINTS[name],
+			docs: docs( LAYOUT_SECTIONS.has( name ) ? name : "landmarks" ),
+			...LAYOUT_SECTIONS.has( name ) && { props: { layout: LAYOUT_PROP } },
 		} ] ),
 	),
 
 	video: {
-		label: "Video",
-		hint: "Embedded video with playback controls.",
+		label: text( "Video", "Video" ),
+		hint: text( "Embedded video with playback controls.", "Eingebettetes Video mit Bedienelementen." ),
+		docs: docs( "video" ),
 		props: {
-			src: { type: "media-file", label: "Video file", required: true },
-			poster: { type: "media-file", label: "Poster image" },
+			src: { type: "media-file", label: text( "Video file", "Videodatei" ), required: true },
+			poster: { type: "media-file", label: text( "Poster image", "Vorschaubild" ) },
 			autoplay: {
 				type: "boolean",
-				label: "Autoplay (muted)",
-				hint: "Not for visitors who asked for reduced motion. For a video across the whole window, use a cover instead.",
+				label: text( "Autoplay (muted)", "Automatisch abspielen (stumm)" ),
+				hint: text(
+					"Not for visitors who asked for reduced motion. For a video across the whole window, use a cover instead.",
+					"Nicht für Besucher, die weniger Bewegung wünschen. Für ein Video über das ganze Fenster eignet sich ein Cover.",
+				),
 				default: false,
 			},
-			loop: { type: "boolean", label: "Loop" },
-			muted: { type: "boolean", label: "Muted" },
+			loop: { type: "boolean", label: text( "Loop", "Endlos wiederholen" ) },
+			muted: { type: "boolean", label: text( "Muted", "Stumm" ) },
 			preload: {
 				type: "enum",
-				label: "Preload",
-				values: [ "none", "metadata", "auto" ],
+				label: text( "Preload", "Vorab laden" ),
+				values: choices(
+					[ "none", "Nothing", "Nichts" ],
+					[ "metadata", "Metadata only", "Nur Metadaten" ],
+					[ "auto", "Whole video", "Ganzes Video" ],
+				),
 				default: "metadata",
 			},
 			label: {
 				type: "text",
-				label: "Accessible label",
-				hint: "Announced by screen readers when the surrounding text does not describe the video.",
+				label: text( "Accessible label", "Zugängliche Bezeichnung" ),
+				hint: text(
+					"Announced by screen readers when the surrounding text does not describe the video.",
+					"Wird von Screenreadern angesagt, wenn der umgebende Text das Video nicht beschreibt.",
+				),
 			},
 		},
 	},
 
 	cover: {
-		label: "Cover",
-		hint: "An image or a video across the full width and height of the window. Anything written inside the section is laid on top of it.",
+		label: text( "Cover", "Cover" ),
+		hint: text(
+			"An image or a video across the full width and height of the window. Anything written inside the section is laid on top of it.",
+			"Ein Bild oder Video über die volle Breite und Höhe des Fensters. Was im Abschnitt steht, liegt darüber.",
+		),
+		docs: docs( "cover" ),
 		props: {
 			src: {
 				type: "media-file",
-				label: "Image or video",
-				hint: "A video plays muted in a loop, with a button to pause it.",
+				label: text( "Image or video", "Bild oder Video" ),
+				hint: text(
+					"A video plays muted in a loop, with a button to pause it.",
+					"Ein Video läuft stumm in Schleife, mit einem Knopf zum Anhalten.",
+				),
 				required: true,
 			},
 			poster: {
 				type: "media-file",
-				label: "Still image",
-				hint: "Only for a video: shown until it plays, and instead of it for visitors who asked for reduced motion.",
+				label: text( "Still image", "Standbild" ),
+				hint: text(
+					"Only for a video: shown until it plays, and instead of it for visitors who asked for reduced motion.",
+					"Nur bei einem Video: zu sehen, bis es läuft, und an seiner Stelle für Besucher, die weniger Bewegung wünschen.",
+				),
 			},
 			focus: {
 				type: "text",
-				label: "Focal point",
-				hint: "Part of the picture that stays visible when the window crops it, e.g. \"center top\" or \"30% 60%\".",
+				label: text( "Focal point", "Fokuspunkt" ),
+				hint: text(
+					"Part of the picture that stays visible when the window crops it, e.g. \"center top\" or \"30% 60%\".",
+					"Bildteil, der sichtbar bleibt, wenn das Fenster beschneidet, z. B. \"center top\" oder \"30% 60%\".",
+				),
 			},
 			label: {
 				type: "text",
-				label: "Description",
-				hint: "Alternative text of the image, or what the video shows. Leave empty when it is decoration only.",
+				label: text( "Description", "Beschreibung" ),
+				hint: text(
+					"Alternative text of the image, or what the video shows. Leave empty when it is decoration only.",
+					"Alternativtext des Bildes oder was das Video zeigt. Leer lassen, wenn es nur Dekoration ist.",
+				),
 			},
 			tone: {
 				type: "enum",
-				label: "Content on top",
-				values: [ "light", "dark" ],
-				hint: "\"light\" over a dark picture, \"dark\" over a bright one. Left unset, the site's design decides.",
+				label: text( "Content on top", "Inhalt darüber" ),
+				values: choices(
+					[ "light", "Light, over a dark picture", "Hell, über dunklem Bild" ],
+					[ "dark", "Dark, over a bright picture", "Dunkel, über hellem Bild" ],
+				),
+				hint: text( "Left unset, the site's design decides.", "Ohne Angabe entscheidet die Gestaltung der Website." ),
+			},
+		},
+	},
+
+	card: {
+		label: text( "Card", "Karte" ),
+		hint: text(
+			"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.",
+			"Eine Einheit für sich – etwa Bild, Überschrift und ein paar Zeilen –, abgesetzt vom Text drumherum. Karten nebeneinander kommen in ein Raster.",
+		),
+		docs: docs( "card" ),
+		props: {
+			link: {
+				type: "page-ref",
+				label: text( "Links to", "Verlinkt auf" ),
+				hint: text(
+					"Makes the whole card a link to this page, with a \"Read more\" naming it for screen readers.",
+					"Macht die ganze Karte zum Link auf diese Seite, mit einem „Weiterlesen“, das sie für Screenreader benennt.",
+				),
+			},
+		},
+	},
+
+	details: {
+		label: text( "Details", "Ausklappbar" ),
+		hint: text(
+			"Content that is collapsed under a title until the reader expands it — for answers in a FAQ, say, or information only some readers need.",
+			"Inhalt, der unter einem Titel zugeklappt ist, bis man ihn aufklappt – etwa Antworten in einer FAQ oder Hinweise, die nur manche brauchen.",
+		),
+		docs: docs( "details" ),
+		props: {
+			summary: {
+				type: "text",
+				label: text( "Title", "Titel" ),
+				hint: text(
+					"Always visible; clicking it expands or collapses the content.",
+					"Immer sichtbar; ein Klick darauf klappt den Inhalt auf oder zu.",
+				),
+				required: true,
+			},
+			open: { type: "boolean", label: text( "Expanded at first", "Anfangs aufgeklappt" ) },
+			group: {
+				type: "text",
+				label: text( "Group", "Gruppe" ),
+				hint: text(
+					"Blocks with the same group name close each other, so only one of them is expanded at a time.",
+					"Blöcke mit demselben Gruppennamen schließen einander, sodass immer nur einer aufgeklappt ist.",
+				),
+			},
+		},
+	},
+
+	grid: {
+		label: text( "Grid", "Raster" ),
+		hint: text(
+			"Puts the blocks written inside side by side in columns, starting a new row when a row is full — a paragraph, an image or an embedded section each fill one cell. On narrow screens the grid drops columns by itself.",
+			"Stellt die Blöcke darin in Spalten nebeneinander und beginnt eine neue Zeile, wenn eine voll ist – ein Absatz, ein Bild oder ein eingebetteter Abschnitt füllt je eine Zelle. Auf schmalen Bildschirmen werden es von selbst weniger Spalten.",
+		),
+		docs: docs( "grid" ),
+		props: {
+			columns: {
+				type: "enum",
+				label: text( "Columns", "Spalten" ),
+				values: GRID_COLUMNS.map( String ),
+				default: String( GRID_COLUMNS[0] ),
+				hint: text(
+					"Most cells side by side, where the screen is wide enough.",
+					"Höchstens so viele Zellen nebeneinander, wo der Bildschirm breit genug ist.",
+				),
 			},
 		},
 	},
 
 	pagelist: {
-		label: "Page list",
-		hint: "Links a configurable number of the site's own pages — the latest posts of a blog, for example. Anything written inside the section is rendered above the list.",
+		label: text( "Page list", "Seitenliste" ),
+		hint: text(
+			"Links a configurable number of the site's own pages — the latest posts of a blog, for example. Anything written inside the section is rendered above the list.",
+			"Verlinkt eine einstellbare Zahl eigener Seiten – etwa die neuesten Beiträge eines Blogs. Was im Abschnitt steht, erscheint über der Liste.",
+		),
+		docs: docs( "pagelist" ),
 		props: {
 			from: {
 				type: "number",
-				label: "Pages to list",
-				hint: "Relative to this page: 1 = its sub-pages (the usual choice), 0 = its siblings.",
+				label: text( "Pages to list", "Welche Seiten" ),
+				hint: text(
+					"Relative to this page: 1 = its sub-pages (the usual choice), 0 = its siblings.",
+					"Ausgehend von dieser Seite: 1 = ihre Unterseiten (der übliche Fall), 0 = ihre Nachbarseiten.",
+				),
 				default: 1,
 			},
 			"from-root": {
 				type: "number",
-				label: "Level from the site root",
-				hint: "Alternative to the relative choice: 1 = top-level pages, 2 = second level. Takes precedence over it.",
+				label: text( "Level from the site root", "Ebene ab Website-Start" ),
+				hint: text(
+					"Alternative to the relative choice: 1 = top-level pages, 2 = second level. Takes precedence over it.",
+					"Statt der relativen Wahl: 1 = oberste Ebene, 2 = zweite Ebene. Hat Vorrang davor.",
+				),
 			},
 			"from-path": {
 				type: "page-ref",
-				label: "Pages below this page",
-				hint: "Lists the sub-pages of the page you pick, wherever this section sits. Takes precedence over both other choices.",
+				label: text( "Pages below this page", "Unterseiten dieser Seite" ),
+				hint: text(
+					"Lists the sub-pages of the page you pick, wherever this section sits. Takes precedence over both other choices.",
+					"Listet die Unterseiten der gewählten Seite, egal wo dieser Abschnitt steht. Hat Vorrang vor beiden anderen Angaben.",
+				),
 			},
 			deep: {
 				type: "boolean",
-				label: "Include deeper levels",
-				hint: "Also lists pages further down, flattened into one list — for posts filed in year or month folders.",
+				label: text( "Include deeper levels", "Tiefere Ebenen einbeziehen" ),
+				hint: text(
+					"Also lists pages further down, flattened into one list — for posts filed in year or month folders.",
+					"Listet auch Seiten weiter unten, in einer flachen Liste – für Beiträge in Jahres- oder Monatsordnern.",
+				),
 			},
 			limit: {
 				type: "number",
-				label: "Number of entries",
-				hint: "0 lists every page found. Left unset on a list with entries per page, every page found is paged through.",
+				label: text( "Number of entries", "Anzahl Einträge" ),
+				hint: text(
+					"0 lists every page found. Left unset on a list with entries per page, every page found is paged through.",
+					"0 listet alle gefundenen Seiten. Ohne Angabe, aber mit Einträgen pro Seite, wird durch alle geblättert.",
+				),
 				default: 5,
 			},
 			offset: {
 				type: "number",
-				label: "Skip entries",
-				hint: "Leaves out this many entries at the start — a second list can continue where the first one ended.",
+				label: text( "Skip entries", "Einträge überspringen" ),
+				hint: text(
+					"Leaves out this many entries at the start — a second list can continue where the first one ended.",
+					"Lässt so viele Einträge am Anfang weg – eine zweite Liste kann dort weitermachen, wo die erste endet.",
+				),
 				default: 0,
 			},
 			sort: {
 				type: "enum",
-				label: "Order",
-				values: [ "order", "date", "date-asc", "title" ],
+				label: text( "Order", "Reihenfolge" ),
+				values: choices(
+					[ "order", "As in the site structure", "Wie in der Seitenstruktur" ],
+					[ "date", "Newest first", "Neueste zuerst" ],
+					[ "date-asc", "Oldest first", "Älteste zuerst" ],
+					[ "title", "By title", "Nach Titel" ],
+				),
 				default: "order",
-				hint: "\"order\" follows the site structure; \"date\" is newest first and needs a date in the target pages.",
+				hint: text(
+					"Ordering by date needs a date in the listed pages.",
+					"Die Sortierung nach Datum braucht ein Datum in den gelisteten Seiten.",
+				),
 			},
-			reverse: { type: "boolean", label: "Reverse the order" },
+			reverse: { type: "boolean", label: text( "Reverse the order", "Reihenfolge umkehren" ) },
 			teaser: {
 				type: "boolean",
-				label: "Show introductory texts",
-				hint: "Each target page contributes its excerpt — from its own excerpt field, or its opening lines.",
+				label: text( "Show introductory texts", "Einleitungstexte zeigen" ),
+				hint: text(
+					"Each target page contributes its excerpt — from its own excerpt field, or its opening lines.",
+					"Jede Zielseite steuert ihren Auszug bei – aus ihrem Auszugsfeld oder ihren ersten Zeilen.",
+				),
 			},
 			images: {
 				type: "boolean",
-				label: "Show teaser images",
-				hint: "Each target page contributes its image field, or the first image in the page.",
+				label: text( "Show teaser images", "Teaserbilder zeigen" ),
+				hint: text(
+					"Each target page contributes its image field, or the first image in the page.",
+					"Jede Zielseite steuert ihr Bildfeld bei oder das erste Bild der Seite.",
+				),
 			},
-			dates: { type: "boolean", label: "Show dates" },
+			dates: { type: "boolean", label: text( "Show dates", "Datum zeigen" ) },
 			"date-style": {
 				type: "enum",
-				label: "Date format",
-				values: [ "short", "medium", "long", "full", "iso" ],
+				label: text( "Date format", "Datumsformat" ),
+				values: choices(
+					[ "short", "Short", "Kurz" ],
+					[ "medium", "Medium", "Mittel" ],
+					[ "long", "Long", "Lang" ],
+					[ "full", "Full, with weekday", "Voll, mit Wochentag" ],
+					[ "iso", "ISO (2020-10-20)", "ISO (2020-10-20)" ],
+				),
 				default: "long",
-				hint: "\"iso\" writes 2020-10-20 in every language; the others follow the page's language.",
+				hint: text(
+					"ISO is the same in every language; the others follow the page's language.",
+					"ISO ist in jeder Sprache gleich; die anderen folgen der Sprache der Seite.",
+				),
 			},
 			"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.",
+				label: text( "Time format", "Uhrzeitformat" ),
+				values: choices(
+					[ "short", "Short", "Kurz" ],
+					[ "medium", "Medium", "Mittel" ],
+					[ "long", "Long", "Lang" ],
+					[ "full", "Full", "Voll" ],
+					[ "iso", "ISO (12:16)", "ISO (12:16)" ],
+				),
+				hint: text( "Left unset, entries show their date only.", "Ohne Angabe zeigen Einträge nur ihr Datum." ),
 			},
 			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.",
+				label: text( "Time zone", "Zeitzone" ),
+				hint: text(
+					"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.",
+					"Zone, in der Datumsangaben gelesen werden, z. B. Europe/Berlin. Standard ist UTC – richtig für ein Datum ohne Uhrzeit.",
+				),
 			},
 			"heading-level": {
 				type: "number",
-				label: "Heading level of the titles",
-				hint: "0 keeps the entries a plain list of links. Use 2–6 for teaser cards, one level below the heading above the list.",
+				label: text( "Heading level of the titles", "Überschriftenebene der Titel" ),
+				hint: text(
+					"0 keeps the entries a plain list of links. Use 2–6 for teaser cards, one level below the heading above the list.",
+					"0 belässt es bei einer einfachen Linkliste. 2–6 für Teaserkarten, eine Ebene unter der Überschrift über der Liste.",
+				),
 				default: 0,
 			},
 			"per-page": {
 				type: "number",
-				label: "Entries per page",
-				hint: "0 shows all of them; anything higher lets the reader page through the list.",
+				label: text( "Entries per page", "Einträge pro Seite" ),
+				hint: text(
+					"0 shows all of them; anything higher lets the reader page through the list.",
+					"0 zeigt alle; ein höherer Wert lässt durch die Liste blättern.",
+				),
 				default: 0,
 			},
 			param: {
 				type: "text",
-				label: "Name of the page parameter",
-				hint: "Only needed when one page carries several paginated lists, so each remembers its own page.",
+				label: text( "Name of the page parameter", "Name des Seitenparameters" ),
+				hint: text(
+					"Only needed when one page carries several paginated lists, so each remembers its own page.",
+					"Nur nötig, wenn eine Seite mehrere blätterbare Listen hat, damit sich jede ihre Seite merkt.",
+				),
 			},
 			"image-sizes": {
 				type: "text",
-				label: "Image widths (sizes)",
-				hint: "CSS sizes descriptor for the teaser images, matching the column they are shown in.",
+				label: text( "Image widths (sizes)", "Bildbreiten (sizes)" ),
+				hint: text(
+					"CSS sizes descriptor for the teaser images, matching the column they are shown in.",
+					"CSS-sizes-Angabe für die Teaserbilder, passend zur Spalte, in der sie stehen.",
+				),
 			},
 			label: {
 				type: "text",
-				label: "Accessible label",
-				hint: "Announced by screen readers to tell this list apart from other lists on the page.",
+				label: text( "Accessible label", "Zugängliche Bezeichnung" ),
+				hint: text(
+					"Announced by screen readers to tell this list apart from other lists on the page.",
+					"Wird von Screenreadern angesagt, um diese Liste von anderen auf der Seite zu unterscheiden.",
+				),
 			},
 		},
 	},
@@ -278,6 +570,10 @@ export function buildSectionManifest( declaredContainers = {}, { adapterVersion
 			entry.hint = decl.hint;
 		}
 
+		if ( decl.docs != null ) {
+			entry.docs = decl.docs;
+		}
+
 		const props = propsFromDeclaration( decl );
 		if ( Object.keys( props ).length > 0 ) {
 			entry.props = { ...entry.props ?? {} , ...props };
@@ -302,6 +598,124 @@ export function buildSectionManifest( declaredContainers = {}, { adapterVersion
 	};
 }
 
+/**
+ * Lists the icons a manifest refers to, from `boolean` props and from the choices
+ * of `enum` props.
+ *
+ * @param {object} manifest manifest object from buildSectionManifest()
+ * @returns {Set<string>} referenced icon names
+ */
+export function iconReferencesOf( manifest ) {
+	const names = new Set();
+
+	for ( const section of Object.values( manifest?.sections ?? {} ) ) {
+		for ( const prop of Object.values( section?.props ?? {} ) ) {
+			if ( typeof prop?.icon === "string" ) {
+				names.add( prop.icon );
+			}
+
+			for ( const choice of Array.isArray( prop?.values ) ? prop.values : [] ) {
+				if ( typeof choice?.icon === "string" ) {
+					names.add( choice.icon );
+				}
+			}
+		}
+	}
+
+	return names;
+}
+
+/**
+ * Folder of the icons Scavold brings for its own section kinds, written from
+ * design/icons.svg by scripts/build-icons.js.
+ */
+export const BUILTIN_ICON_DIR = fileURLToPath( new URL( "../icons/", import.meta.url ) );
+
+/**
+ * Reads the icons available to a site: Scavold's own, and those the site keeps in
+ * `{cwd}/.cratly/icons/`, which replace Scavold's of the same name. A file whose name
+ * is not a valid icon name is skipped and reported, since nothing could refer to it.
+ *
+ * @param {string} cwd project root
+ * @param {object} [options]
+ * @param {Function} [options.warn] sink for reports
+ * @param {string|null} [options.builtin] folder of Scavold's own icons, null for none
+ * @returns {Promise<Map<string,string>>} icon name → SVG markup
+ */
+export async function readIcons( cwd, { warn = console.warn, builtin = BUILTIN_ICON_DIR } = {} ) {
+	const own = builtin ? await readIconDir( builtin, warn ) : new Map();
+	const site = await readIconDir( join( cwd, SECTION_MANIFEST_DIR, ICON_DIR ), warn );
+
+	return new Map( [ ...own, ...site ] );
+}
+
+/**
+ * Reads the SVG files in one folder as icons named by their base names.
+ *
+ * @param {string} dir
+ * @param {Function} warn sink for reports
+ * @returns {Promise<Map<string,string>>} icon name → SVG markup
+ */
+async function readIconDir( dir, warn ) {
+	let entries;
+	try {
+		entries = await readdir( dir, { withFileTypes: true } );
+	} catch {
+		return new Map();
+	}
+
+	const names = [];
+
+	for ( const entry of entries ) {
+		if ( !entry.isFile() || !entry.name.endsWith( ".svg" ) ) {
+			continue;
+		}
+
+		const name = entry.name.slice( 0, -4 );
+
+		if ( ICON_NAME.test( name ) ) {
+			names.push( name );
+		} else {
+			warn( "[scavold] icon %s is ignored: a name has lower-case letters, digits and dashes only",
+				join( dir, entry.name ) );
+		}
+	}
+
+	const markup = await Promise.all( names.map( name => readFile( join( dir, `${name}.svg` ), "utf-8" ) ) );
+
+	return new Map( names.map( ( name, index ) => [ name, markup[index].trim() ] ) );
+}
+
+/**
+ * Embeds the icons a manifest refers to, so the editor gets them with the manifest.
+ * Icons nothing refers to stay out; a reference to an icon that does not exist is
+ * reported and left for the editor to fall back on its plain control.
+ *
+ * @param {object} manifest manifest object from buildSectionManifest(), adjusted in place
+ * @param {Map<string,string>} available icons from readIcons()
+ * @param {object} [options]
+ * @param {Function} [options.warn] sink for reports
+ * @returns {object} the manifest
+ */
+export function embedIcons( manifest, available, { warn = console.warn } = {} ) {
+	const icons = {};
+
+	for ( const name of [...iconReferencesOf( manifest )].sort() ) {
+		if ( available.has( name ) ) {
+			icons[name] = available.get( name );
+		} else {
+			warn( "[scavold] icon '%s' is used in .cratly.config.yaml, but there is no %s/%s/%s.svg",
+				name, SECTION_MANIFEST_DIR, ICON_DIR, name );
+		}
+	}
+
+	if ( Object.keys( icons ).length > 0 ) {
+		manifest.icons = icons;
+	}
+
+	return manifest;
+}
+
 /**
  * Writes a section-type manifest to `{cwd}/.cratly/sections.json`, creating the
  * folder as needed. Skips the write when the on-disk content is already