Support custom example title and description via <script module> exports

Examples can now export title and description from a <script module> block to override the filename-derived title and add a description. These are extracted by the catalog generator, displayed in the component layout and example listings, and indexed for search (both browse page filter and command+k).

Author: techniq

docs/scripts/generate-example-catalog.ts

@@ -96,6 +96,26 @@ function extractComponentsFromExample(
 	return components.sort((a, b) => a.lineNumber - b.lineNumber);
 }
 
+/**
+ * Extract module-level exports (title, description) from a <script module> block
+ */
+function extractModuleExports(filePath: string): { title?: string; description?: string } {
+	const content = fs.readFileSync(filePath, 'utf-8');
+	const moduleMatch = content.match(/<script\s+module>([\s\S]*?)<\/script>/);
+	if (!moduleMatch) return {};
+
+	const moduleContent = moduleMatch[1];
+	const result: { title?: string; description?: string } = {};
+
+	const titleMatch = moduleContent.match(/export\s+const\s+title\s*=\s*['"`](.+?)['"`]/);
+	if (titleMatch) result.title = titleMatch[1];
+
+	const descMatch = moduleContent.match(/export\s+const\s+description\s*=\s*['"`](.+?)['"`]/);
+	if (descMatch) result.description = descMatch[1];
+
+	return result;
+}
+
 /**
  * Get all examples for a specific component
  */
@@ -119,12 +139,21 @@ function getComponentExamples(componentName: string, allComponents: string[]): E
 			// Extract all components used in this example
 			const componentsInExample = extractComponentsFromExample(filePath, allComponents);
 
-			examples.push({
+			// Extract module-level exports
+			const moduleExports = extractModuleExports(filePath);
+
+			const info: ExampleInfo = {
 				name: exampleName,
-				title: exampleName.replaceAll('-', ' '),
+				title: moduleExports.title ?? exampleName.replaceAll('-', ' '),
 				path: `/docs/components/${componentName}/${exampleName}`,
 				components: componentsInExample
-			});
+			};
+
+			if (moduleExports.description) {
+				info.description = moduleExports.description;
+			}
+
+			examples.push(info);
 		}
 	}
 

docs/src/examples/catalog/Axis.json

@@ -4937,6 +4937,48 @@
       "lineNumber": 59,
       "line": "<Axis placement=\"bottom\" rule />"
     },
+    {
+      "example": "basic",
+      "component": "Trail",
+      "path": "/docs/components/Trail/basic",
+      "lineNumber": 12,
+      "line": "<Axis placement=\"left\" grid rule />"
+    },
+    {
+      "example": "basic",
+      "component": "Trail",
+      "path": "/docs/components/Trail/basic",
+      "lineNumber": 13,
+      "line": "<Axis placement=\"bottom\" rule />"
+    },
+    {
+      "example": "tdf-stage",
+      "component": "Trail",
+      "path": "/docs/components/Trail/tdf-stage",
+      "lineNumber": 25,
+      "line": "<Axis placement=\"left\" grid label=\"Latitude\" />"
+    },
+    {
+      "example": "tdf-stage",
+      "component": "Trail",
+      "path": "/docs/components/Trail/tdf-stage",
+      "lineNumber": 26,
+      "line": "<Axis placement=\"bottom\" label=\"Longitude\" />"
+    },
+    {
+      "example": "variable-width",
+      "component": "Trail",
+      "path": "/docs/components/Trail/variable-width",
+      "lineNumber": 13,
+      "line": "<Axis placement=\"left\" grid rule />"
+    },
+    {
+      "example": "variable-width",
+      "component": "Trail",
+      "path": "/docs/components/Trail/variable-width",
+      "lineNumber": 14,
+      "line": "<Axis placement=\"bottom\" rule />"
+    },
     {
       "example": "pan-zoom-axes",
       "component": "TransformContext",
@@ -5057,5 +5099,5 @@
       "line": "<Axis placement=\"bottom\" rule />"
     }
   ],
-  "updatedAt": "2026-04-02T19:16:00.334Z"
+  "updatedAt": "2026-04-03T15:31:23.718Z"
 }

docs/src/examples/catalog/Chart.json

@@ -2084,6 +2084,13 @@
       "lineNumber": 58,
       "line": "<Chart"
     },
+    {
+      "example": "interpolating-projections",
+      "component": "GeoPath",
+      "path": "/docs/components/GeoPath/interpolating-projections",
+      "lineNumber": 169,
+      "line": "<Chart"
+    },
     {
       "example": "sketchy-globe",
       "component": "GeoPath",
@@ -3820,6 +3827,27 @@
       "lineNumber": 41,
       "line": "<Chart"
     },
+    {
+      "example": "basic",
+      "component": "Trail",
+      "path": "/docs/components/Trail/basic",
+      "lineNumber": 10,
+      "line": "<Chart {data} x=\"date\" y=\"value\" yDomain={[0, null]} yNice padding={25} height={300}>"
+    },
+    {
+      "example": "tdf-stage",
+      "component": "Trail",
+      "path": "/docs/components/Trail/tdf-stage",
+      "lineNumber": 15,
+      "line": "<Chart"
+    },
+    {
+      "example": "variable-width",
+      "component": "Trail",
+      "path": "/docs/components/Trail/variable-width",
+      "lineNumber": 11,
+      "line": "<Chart {data} x=\"date\" y=\"value\" yDomain={[0, null]} yNice r=\"value\" rScale={scaleLinear()} rRange={[2, 16]} padding={25} height={300}>"
+    },
     {
       "example": "pan-zoom-axes",
       "component": "TransformContext",
@@ -3996,5 +4024,5 @@
       "line": "<Chart {data} x=\"x\" y=\"y\" height={400}>"
     }
   ],
-  "updatedAt": "2026-04-02T19:16:00.836Z"
+  "updatedAt": "2026-04-03T15:31:24.127Z"
 }

docs/src/examples/catalog/GeoPath.json

@@ -144,6 +144,33 @@
         }
       ]
     },
+    {
+      "name": "interpolating-projections",
+      "title": "interpolating projections",
+      "path": "/docs/components/GeoPath/interpolating-projections",
+      "components": [
+        {
+          "component": "Chart",
+          "lineNumber": 169,
+          "line": "<Chart"
+        },
+        {
+          "component": "Layer",
+          "lineNumber": 177,
+          "line": "<Layer>"
+        },
+        {
+          "component": "GeoPath",
+          "lineNumber": 178,
+          "line": "<GeoPath geojson={{ type: 'Sphere' }} class=\"stroke-surface-content/20 fill-none\" />"
+        },
+        {
+          "component": "Graticule",
+          "lineNumber": 180,
+          "line": "<Graticule class=\"stroke-surface-content/10\" />"
+        }
+      ]
+    },
     {
       "name": "sketchy-globe",
       "title": "sketchy globe",
@@ -835,6 +862,20 @@
       "lineNumber": 81,
       "line": "<GeoPath"
     },
+    {
+      "example": "interpolating-projections",
+      "component": "GeoPath",
+      "path": "/docs/components/GeoPath/interpolating-projections",
+      "lineNumber": 178,
+      "line": "<GeoPath geojson={{ type: 'Sphere' }} class=\"stroke-surface-content/20 fill-none\" />"
+    },
+    {
+      "example": "interpolating-projections",
+      "component": "GeoPath",
+      "path": "/docs/components/GeoPath/interpolating-projections",
+      "lineNumber": 182,
+      "line": "<GeoPath geojson={land} class=\"fill-surface-content/15\" />"
+    },
     {
       "example": "sketchy-globe",
       "component": "GeoPath",
@@ -1382,5 +1423,5 @@
       "line": "<GeoPath"
     }
   ],
-  "updatedAt": "2026-04-02T19:16:01.400Z"
+  "updatedAt": "2026-04-03T15:31:24.682Z"
 }

docs/src/examples/catalog/Graticule.json

@@ -70,6 +70,13 @@
       "lineNumber": 74,
       "line": "<Graticule class=\"stroke-surface-content/20\" />"
     },
+    {
+      "example": "interpolating-projections",
+      "component": "GeoPath",
+      "path": "/docs/components/GeoPath/interpolating-projections",
+      "lineNumber": 180,
+      "line": "<Graticule class=\"stroke-surface-content/10\" />"
+    },
     {
       "example": "sketchy-globe",
       "component": "GeoPath",
@@ -176,5 +183,5 @@
       "line": "<Graticule class=\"stroke-surface-content/10\" />"
     }
   ],
-  "updatedAt": "2026-04-02T19:16:01.558Z"
+  "updatedAt": "2026-04-03T15:31:24.827Z"
 }

docs/src/examples/catalog/Layer.json

@@ -1885,6 +1885,13 @@
       "lineNumber": 72,
       "line": "<Layer>"
     },
+    {
+      "example": "interpolating-projections",
+      "component": "GeoPath",
+      "path": "/docs/components/GeoPath/interpolating-projections",
+      "lineNumber": 177,
+      "line": "<Layer>"
+    },
     {
       "example": "sketchy-globe",
       "component": "GeoPath",
@@ -3726,6 +3733,27 @@
       "lineNumber": 57,
       "line": "<Layer>"
     },
+    {
+      "example": "basic",
+      "component": "Trail",
+      "path": "/docs/components/Trail/basic",
+      "lineNumber": 11,
+      "line": "<Layer>"
+    },
+    {
+      "example": "tdf-stage",
+      "component": "Trail",
+      "path": "/docs/components/Trail/tdf-stage",
+      "lineNumber": 24,
+      "line": "<Layer>"
+    },
+    {
+      "example": "variable-width",
+      "component": "Trail",
+      "path": "/docs/components/Trail/variable-width",
+      "lineNumber": 12,
+      "line": "<Layer>"
+    },
     {
       "example": "pan-zoom-axes",
       "component": "TransformContext",
@@ -3916,5 +3944,5 @@
       "line": "<Layer onpointermove={onPointerMove}>"
     }
   ],
-  "updatedAt": "2026-04-02T19:16:01.850Z"
+  "updatedAt": "2026-04-03T15:31:25.004Z"
 }

docs/src/examples/catalog/Spline.json

@@ -1338,6 +1338,13 @@
       "lineNumber": 45,
       "line": "<Spline y=\"value\" {curve} class=\"stroke-[1.5]\" />"
     },
+    {
+      "example": "tdf-stage",
+      "component": "Trail",
+      "path": "/docs/components/Trail/tdf-stage",
+      "lineNumber": 28,
+      "line": "<Spline class=\"stroke-1 stroke-surface-content\" />"
+    },
     {
       "example": "playground",
       "component": "TransformContext",
@@ -1346,5 +1353,5 @@
       "line": "<Spline curve={config.curve} motion=\"tween\" />"
     }
   ],
-  "updatedAt": "2026-04-02T19:16:02.594Z"
+  "updatedAt": "2026-04-03T15:31:25.665Z"
 }

docs/src/examples/catalog/types.ts

@@ -23,8 +23,10 @@ export interface ComponentUsageInExample {
 export interface ExampleInfo {
 	/** The name of the example (filename without .svelte extension) */
 	name: string;
-	/** Human-readable title (name with hyphens replaced by spaces) */
+	/** Human-readable title (from <script module> export or name with hyphens replaced by spaces) */
 	title: string;
+	/** Optional description (from <script module> export) */
+	description?: string;
 	/** The URL path to view the example */
 	path: string;
 	/** All components used in this example */

docs/src/lib/components/ExampleLink.svelte

@@ -12,13 +12,15 @@
 	let {
 		component,
 		example,
+		title,
 		showComponent,
 		variant = 'default',
 		aspect = undefined,
 		...restProps
 	}: {
 		component: string;
 		example: string;
+		title?: string;
 		showComponent?: boolean;
 		variant?: ComponentProps<typeof ImageLink>['variant'];
 		aspect?: ComponentProps<typeof ExampleScreenshot>['aspect'];
@@ -67,6 +69,6 @@
 				class="shrink-0 text-surface-content/50 group-hover:text-primary-content/50"
 			/>
 		{/if}
-		<span class="first-letter:capitalize truncate">{example.replaceAll('-', ' ')}</span>
+		<span class="first-letter:capitalize truncate">{title ?? example.replaceAll('-', ' ')}</span>
 	{/snippet}
 </ImageLink>

docs/src/lib/components/ExampleListing.svelte

@@ -124,7 +124,7 @@
 			class="grid grid-cols-(--column-count) gap-4"
 		>
 			{#each examples as example (example.name)}
-				<ExampleLink component={catalog.component} example={example.name} />
+				<ExampleLink component={catalog.component} example={example.name} title={example.title} />
 			{/each}
 		</div>
 	{:else if catalog.examples?.length}