@sprig-and-prose/tutorial-svelte 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sprig-and-prose/tutorial-svelte",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "A calm SvelteKit package that transforms markdown files into paged tutorial routes",
   "main": "src/index.js",
@@ -9,6 +9,7 @@
     ".": "./src/index.js",
     "./kit": {
       "types": "./src/kit/index.d.ts",
+      "import": "./src/kit/index.js",
       "default": "./src/kit/index.js"
     },
     "./kit/Tutorial.svelte": "./src/kit/Tutorial.svelte"

package/src/kit/Tutorial.svelte

@@ -3,6 +3,7 @@
 		| {
 				kind: 'page';
 				title: string;
+				segmentTitle?: string;
 				html: string;
 				nav: { previous?: string; next?: string };
 		  }
@@ -32,9 +33,13 @@
 </script>
 
 {#if data.kind === 'page'}
-	<h1>{data.title}</h1>
-	{@html data.html}
-	<nav class="tutorial-nav">
+	<div class="tutorial-page">
+		<h1>{data.title}</h1>
+		{#if data.segmentTitle}
+			<p class="subtitle">{data.segmentTitle}</p>
+		{/if}
+		{@html data.html}
+		<nav class="tutorial-nav">
 		{#if data.nav.previous}
 			<a href={data.nav.previous} class="nav-link nav-previous">Previous</a>
 		{:else}
@@ -45,7 +50,8 @@
 		{:else}
 			<span class="nav-link nav-next nav-placeholder"></span>
 		{/if}
-	</nav>
+		</nav>
+	</div>
 {:else if data.kind === 'index'}
 	<div class="directory-index">
 		<h1>Contents</h1>
@@ -161,5 +167,22 @@
 	.error-link:hover {
 		color: var(--text-secondary);
 	}
+
+	.tutorial-page {
+		max-width: 70ch;
+		margin: 0 auto;
+	}
+
+	.tutorial-page h1 {
+		margin: 0;
+	}
+
+	.tutorial-page .subtitle {
+		margin: 0 0 var(--sp-space-12, 3rem) 0;
+		font-size: var(--sp-font-body, 1rem);
+		line-height: 1.6;
+		color: var(--text-color, #111827);
+		margin-top: 0;
+	}
 </style>
 

package/src/lib/createTutorialEntries.js

@@ -15,7 +15,32 @@ export function createTutorialEntries({ routeBase, modules, enableDirectoryIndex
 
 	return async () => {
 		const entries = generateEntries(modules, routeBase, enableDirectoryIndex);
-		return entries;
+		// Ensure we always return an array, even if empty
+		if (!Array.isArray(entries)) {
+			console.warn('[tutorial-svelte] generateEntries did not return an array:', entries);
+			return [];
+		}
+		// Ensure all entries have the correct structure
+		// For catch-all routes, SvelteKit expects { path: "..." } not { params: { path: "..." } }
+		const validEntries = entries.filter((entry) => {
+			if (!entry || typeof entry !== 'object') {
+				return false;
+			}
+			// CRITICAL: For catch-all routes, path must be directly on the entry object
+			if (!('path' in entry)) {
+				return false;
+			}
+			const path = entry.path;
+			if (typeof path !== 'string' || path.length === 0) {
+				return false;
+			}
+			// SvelteKit doesn't allow paths starting or ending with /
+			if (path.startsWith('/') || path.endsWith('/')) {
+				return false;
+			}
+			return true;
+		});
+		return validEntries;
 	};
 }
 

package/src/lib/createTutorialLoad.js

@@ -77,13 +77,31 @@ export function createTutorialLoad({ routeBase, modules, renderMarkdown, enableD
 				content = String(module.default);
 			}
 
-			const { pages, hasH1 } = parseSegment(content);
+			const { pages, segmentTitle, hasH1, hasH2, h1Count, h2Count } = parseSegment(content);
 
-			if (!hasH1 || pages.length === 0) {
+			// Validate H1: must be exactly 1
+			if (h1Count === 0) {
+				return {
+					kind: 'error',
+					code: 'no_h1',
+					message: 'I couldn\'t find a main title. Each tutorial file needs exactly one `#` heading at the top.',
+				};
+			}
+
+			if (h1Count > 1) {
+				return {
+					kind: 'error',
+					code: 'multiple_h1',
+					message: 'I found multiple main titles. Each tutorial file should have exactly one `#` heading.',
+				};
+			}
+
+			// Validate H2: must be 1 or more
+			if (!hasH2 || pages.length === 0) {
 				return {
 					kind: 'error',
 					code: 'no_pages',
-					message: 'I couldn\'t find any pages in this file yet. Pages start with `#` (H1) titles.',
+					message: 'I couldn\'t find any pages in this file yet. Pages start with `##` (H2) titles.',
 				};
 			}
 
@@ -97,11 +115,11 @@ export function createTutorialLoad({ routeBase, modules, renderMarkdown, enableD
 			}
 
 			const page = pages[resolved.pageNum - 1];
-			// Strip the H1 heading from content since we render title separately
-			// Remove the first line if it's an H1 heading
+			// Strip the H2 heading from content since we render title separately
+			// Remove the first line if it's an H2 heading
 			let contentToRender = page.content;
 			const lines = contentToRender.split('\n');
-			if (lines.length > 0 && lines[0].trim().startsWith('# ') && !lines[0].trim().startsWith('##')) {
+			if (lines.length > 0 && lines[0].trim().startsWith('## ') && !lines[0].trim().startsWith('###')) {
 				contentToRender = lines.slice(1).join('\n').replace(/^\s+/, '');
 			}
 			const html = await renderMarkdown(contentToRender);
@@ -112,6 +130,7 @@ export function createTutorialLoad({ routeBase, modules, renderMarkdown, enableD
 				kind: 'page',
 				html,
 				title: page.title,
+				segmentTitle: segmentTitle || '',
 				page: resolved.pageNum,
 				totalPages: pages.length,
 				nav,

package/src/lib/parse.js

@@ -1,38 +1,72 @@
 /**
- * Split markdown content on H1 headings (# )
- * Ignores H1 headings inside fenced code blocks (```)
+ * Split markdown content on H2 headings (## )
+ * Validates exactly one H1 heading (# ) and one or more H2 headings
+ * Ignores headings inside fenced code blocks (```)
  * @param {string} markdownContent - Raw markdown content
- * @returns {{ pages: Array<{ title: string, content: string }>, hasH1: boolean }}
+ * @returns {{ pages: Array<{ title: string, content: string }>, segmentTitle: string | null, hasH1: boolean, hasH2: boolean, h1Count: number, h2Count: number }}
  */
 export function parseSegment(markdownContent) {
 	const lines = markdownContent.split('\n');
-	const pages = [];
-	let currentPage = null;
-	let hasH1 = false;
 	let inCodeBlock = false;
+	let segmentTitle = null;
+	let h1Count = 0;
+	let h2Count = 0;
 
+	// First pass: find and validate H1 (must be exactly 1)
 	for (let i = 0; i < lines.length; i++) {
 		const line = lines[i];
 		const trimmed = line.trim();
 
 		// Check for fenced code blocks (``` or ~~~)
-		// Match 3 or more backticks or tildes at the start of the line
-		if (/^[`~]{3,}/.test(trimmed)) {
-			// Toggle code block state
+		// Must check the raw line (not trimmed) to catch code block fences with leading whitespace
+		const rawTrimmed = line.trimStart();
+		if (/^[`~]{3,}/.test(rawTrimmed)) {
 			inCodeBlock = !inCodeBlock;
+			continue;
 		}
 
-		// Only check for H1 if we're not inside a code block
+		// Check for H1 (but not H2) - only if we're not inside a code block
 		if (!inCodeBlock && trimmed.startsWith('# ') && !trimmed.startsWith('##')) {
-			hasH1 = true;
+			h1Count++;
+			if (h1Count === 1) {
+				// Extract the segment title from the first (and should be only) H1
+				segmentTitle = line.replace(/^#\s+/, '').trim();
+			}
+		}
+	}
+
+	// Second pass: split on H2 headings
+	const pages = [];
+	let currentPage = null;
+	inCodeBlock = false;
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		const trimmed = line.trim();
+
+		// Check for fenced code blocks (``` or ~~~)
+		// Must check the raw line (not trimmed) to catch code block fences with leading whitespace
+		const rawTrimmed = line.trimStart();
+		if (/^[`~]{3,}/.test(rawTrimmed)) {
+			inCodeBlock = !inCodeBlock;
+			// Still add the code block fence line to content, but don't process it as a heading
+			if (currentPage !== null) {
+				currentPage.content += line + '\n';
+			}
+			continue;
+		}
+
+		// Check for H2 if we're not inside a code block
+		if (!inCodeBlock && trimmed.startsWith('## ') && !trimmed.startsWith('###')) {
+			h2Count++;
 
 			// If we have a previous page, save it
 			if (currentPage !== null) {
 				pages.push(currentPage);
 			}
 
-			// Extract title (remove the # and trim)
-			const title = line.replace(/^#\s+/, '').trim();
+			// Extract title (remove the ## and trim)
+			const title = line.replace(/^##\s+/, '').trim();
 
 			// Start new page
 			currentPage = {
@@ -57,7 +91,11 @@ export function parseSegment(markdownContent) {
 
 	return {
 		pages,
-		hasH1,
+		segmentTitle,
+		hasH1: h1Count === 1,
+		hasH2: h2Count > 0,
+		h1Count,
+		h2Count,
 	};
 }
 

package/src/lib/routes.js

@@ -79,7 +79,7 @@ export function resolveRoute(pathArray, modules, routeBase) {
  * @param {Record<string, any>} modules - Modules from import.meta.glob()
  * @param {string} routeBase - Base route path
  * @param {boolean} enableDirectoryIndex - Whether to generate directory index entries
- * @returns {Array<{ path: string[] }>}
+ * @returns {Array<{ path: string }>}
  */
 export function generateEntries(modules, routeBase, enableDirectoryIndex) {
 	const entries = [];
@@ -87,6 +87,11 @@ export function generateEntries(modules, routeBase, enableDirectoryIndex) {
 
 	// Generate entries for all pages of all segments
 	for (const item of discovered) {
+		// Skip items with empty routePath
+		if (!item.routePath || item.routePath.trim() === '') {
+			continue;
+		}
+
 		// Get markdown content to count pages
 		const module = modules[item.filePath];
 		let content = '';
@@ -105,25 +110,34 @@ export function generateEntries(modules, routeBase, enableDirectoryIndex) {
 			content = String(module.default);
 		}
 
-		const { pages, hasH1 } = parseSegment(content);
+		const { pages, hasH1, hasH2, h1Count } = parseSegment(content);
 
-		if (!hasH1 || pages.length === 0) {
-			// Skip files with no H1 headings
+		// Skip files that don't meet validation requirements
+		// Must have exactly 1 H1 and at least 1 H2
+		if (h1Count !== 1 || !hasH2 || pages.length === 0) {
+			// Skip files that don't meet the new requirements
 			continue;
 		}
 
-		const segmentPathParts = item.routePath.split('/');
+		const segmentPathParts = item.routePath.split('/').filter(Boolean);
+
+		// Skip if routePath is empty (shouldn't happen, but be safe)
+		if (segmentPathParts.length === 0) {
+			continue;
+		}
 
 		// Generate entry for each page
 		for (let pageNum = 1; pageNum <= pages.length; pageNum++) {
+			const pathString = [...segmentPathParts, String(pageNum)].join('/');
 			entries.push({
-				path: [...segmentPathParts, String(pageNum)],
+				path: pathString,
 			});
 		}
 
 		// Generate stub entry for segment root
+		const segmentPathString = segmentPathParts.join('/');
 		entries.push({
-			path: segmentPathParts,
+			path: segmentPathString,
 		});
 
 		// Generate directory index entries if enabled
@@ -135,18 +149,23 @@ export function generateEntries(modules, routeBase, enableDirectoryIndex) {
 
 				// Check if we've already added this directory
 				const exists = entries.some(
-					(e) => e.path.length === dirPath.length && e.path.join('/') === dirPathStr
+					(e) => e.path === dirPathStr
 				);
 
 				if (!exists) {
 					entries.push({
-						path: dirPath,
+						path: dirPathStr,
 					});
 				}
 			}
 		}
 	}
 
-	return entries;
+	// Filter out any entries with empty or invalid paths
+	// SvelteKit requires catch-all routes to have at least one segment
+	return entries.filter((entry) => {
+		const path = entry.path;
+		return typeof path === 'string' && path.length > 0 && !path.startsWith('/') && !path.endsWith('/');
+	});
 }