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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sprig-and-prose/tutorial-svelte",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "description": "A calm SvelteKit package that transforms markdown files into paged tutorial routes",
   "main": "src/index.js",

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/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

@@ -110,10 +110,12 @@ 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;
 		}