@sprig-and-prose/tutorial-svelte 0.1.0

package/README.md

@@ -0,0 +1,251 @@
+# @sprig-and-prose/tutorial-svelte
+
+A calm Svelte/SvelteKit tutorial renderer.
+
+This package turns a directory of Markdown files into small, paged tutorial routes.
+It is designed for teaching small ideas that build gently, without requiring a custom format or a configuration file.
+
+The filesystem is the structure.
+
+---
+
+## What this is
+
+- A renderer for **paged markdown** (one file becomes multiple pages).
+- A router-friendly model where **content paths mirror URL paths**.
+- A calm default UX:
+  - readable typography
+  - low pressure navigation
+  - gentle error states
+  - optional directory “index” pages for orientation
+
+## What this is not
+
+- A general-purpose Markdown CMS
+- A documentation framework
+- A system with rich frontmatter, plugins, or a complex config graph
+
+If you want heavy customization, use a general Markdown tool.
+If you want calm structure that “just works,” this is for you.
+
+---
+
+## Conceptual model
+
+### Content root
+
+You choose a content root directory, for example:
+
+```
+
+src/content
+
+```
+
+Inside it, you create tutorial content:
+
+```
+
+src/content/
+  greenhouse/
+    arc1/
+      intro.md
+      noticing.md
+      placing.md
+      finishing.md
+  another-tutorial/
+...
+
+```
+
+### Routes mirror the content tree
+
+Given a tutorial root (your site route root), for example:
+
+```
+
+/tutorial
+
+```
+
+The file:
+
+```
+
+src/content/greenhouse/arc1/intro.md
+
+```
+
+becomes:
+
+```
+
+/tutorial/greenhouse/arc1/intro/1
+/tutorial/greenhouse/arc1/intro/2
+/tutorial/greenhouse/arc1/intro/3
+...
+
+```
+
+And:
+
+```
+
+/tutorial/greenhouse/arc1/intro
+
+```
+
+redirects to:
+
+```
+
+/tutorial/greenhouse/arc1/intro/1
+
+````
+
+---
+
+## Pages inside a Markdown file
+
+A single `.md` file becomes a **segment** made up of **pages**.
+
+### Page boundaries
+
+Each page begins with an H1 heading:
+
+```md
+# A first page title
+
+Some text.
+
+# A second page title
+
+More text.
+````
+
+Each H1 creates a new page.
+
+### Requirement: at least one H1
+
+A markdown file must contain at least one `# ` H1 heading.
+
+If a file contains **no H1 headings**, the tutorial will not render pages from it.
+Instead, the UI should show a calm message like:
+
+> “I couldn’t find any pages in this file yet.
+> Pages start with `#` (H1) titles.”
+
+This is intentional: it keeps tutorials structured and predictable.
+
+---
+
+## Navigation
+
+Within a segment:
+
+* “Next” and “Previous” are auto-generated based on page order in the file.
+* The UI should be readable and low-pressure.
+* Navigation should feel like **turning a page**, not completing a task.
+
+### Linking between segments
+
+Branching and rejoining are handled with normal hyperlinks.
+
+For example, a “fork” page can link to two other segment routes:
+
+* `/tutorial/greenhouse/arc1/branch-a/1`
+* `/tutorial/greenhouse/arc1/branch-b/1`
+
+A “rejoin” happens when both branches link back to a shared segment.
+
+No special syntax is required.
+
+---
+
+## Directory index pages (orientation)
+
+By default, directories are explorable.
+
+If a user visits a directory path, for example:
+
+```
+/tutorial/greenhouse/arc1
+```
+
+the UI renders a calm index page listing child items (folders and markdown segments).
+
+This page is intended to be an orientation aid, not a dense site map.
+
+### Turning directory exploration off
+
+Some tutorials should be experienced only via authored links.
+
+For that, directory index pages can be disabled via an option:
+
+* `enableDirectoryIndex: false`
+
+When disabled:
+
+* visiting `/tutorial/greenhouse/arc1` should return a gentle “not found” state
+  (or a minimal message that directory exploration is disabled)
+* direct segment routes (e.g. `/tutorial/greenhouse/arc1/intro/1`) should still work
+
+---
+
+## Error handling (calm by design)
+
+### Page number out of range
+
+If a user visits a page that doesn’t exist (e.g. `/tutorial/.../intro/99`), the UI should show:
+
+* a calm message (“That page doesn’t exist.”)
+* a suggestion (“Try the first page.”)
+* a link back to `/1`
+
+Avoid raw stack traces and avoid loud error styling.
+
+### Missing file / unknown path
+
+If a route does not map to any markdown file, the UI should show a calm “not found” state.
+
+### Markdown file exists but has no H1
+
+Show the “no pages found” message described above.
+
+---
+
+## SvelteKit integration expectations
+
+This package is intended to be used from a SvelteKit catch-all route, for example:
+
+```
+src/routes/tutorial/[...path]/+page.ts
+```
+
+The integration should:
+
+* map `path` to a markdown file under the content root
+* parse markdown into pages by splitting on H1
+* render one page at a time
+
+---
+
+## Options (minimal)
+
+The package should support a small set of options:
+
+* `routeBase` — the base route (e.g. `/tutorial`)
+* `contentRoot` — the content directory (e.g. `src/content`)
+* `enableDirectoryIndex` — default `true`
+
+No other options are required for v1.
+
+---
+
+## Design goals
+
+* Calm, human-first reading experience
+* Minimal authoring rules
+* No required config file
+* Deterministic routing and navigation
+* Supports branching through links, not through tutorial “logic”

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@sprig-and-prose/tutorial-svelte",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A calm SvelteKit package that transforms markdown files into paged tutorial routes",
+  "main": "src/index.js",
+  "svelte": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./kit": {
+      "types": "./src/kit/index.d.ts",
+      "default": "./src/kit/index.js"
+    },
+    "./kit/Tutorial.svelte": "./src/kit/Tutorial.svelte"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "svelte",
+    "sveltekit",
+    "tutorial",
+    "markdown",
+    "ssg"
+  ],
+  "author": "",
+  "license": "MIT",
+  "peerDependencies": {
+    "@sveltejs/kit": "^2.0.0",
+    "svelte": "^5.0.0"
+  },
+  "devDependencies": {
+    "@sveltejs/kit": "^2.49.2",
+    "@types/node": "^22.0.0",
+    "svelte": "^5.46.0",
+    "typescript": "^5.7.2"
+  }
+}
+

package/src/index.js

@@ -0,0 +1,3 @@
+export { createTutorialLoad } from './lib/createTutorialLoad.js';
+export { createTutorialEntries } from './lib/createTutorialEntries.js';
+

package/src/kit/Tutorial.svelte

@@ -0,0 +1,165 @@
+<script lang="ts">
+	type TutorialData =
+		| {
+				kind: 'page';
+				title: string;
+				html: string;
+				nav: { previous?: string; next?: string };
+		  }
+		| {
+				kind: 'index';
+				items: Array<{ name: string; path: string }>;
+		  }
+		| {
+				kind: 'stub';
+				firstPagePath: string;
+		  }
+		| {
+				kind: 'error';
+				message: string;
+				hint?: string;
+				code?: string;
+		  };
+
+	export let data: TutorialData;
+
+	let indexItems: Array<{ name: string; path: string }> = [];
+	$: if (data.kind === 'index') {
+		indexItems = data.items;
+	} else {
+		indexItems = [];
+	}
+</script>
+
+{#if data.kind === 'page'}
+	<h1>{data.title}</h1>
+	{@html data.html}
+	<nav class="tutorial-nav">
+		{#if data.nav.previous}
+			<a href={data.nav.previous} class="nav-link nav-previous">Previous</a>
+		{:else}
+			<span class="nav-link nav-previous nav-placeholder"></span>
+		{/if}
+		{#if data.nav.next}
+			<a href={data.nav.next} class="nav-link nav-next">Next</a>
+		{:else}
+			<span class="nav-link nav-next nav-placeholder"></span>
+		{/if}
+	</nav>
+{:else if data.kind === 'index'}
+	<div class="directory-index">
+		<h1>Contents</h1>
+		<ul class="index-list">
+			{#each indexItems as item}
+				<li class="index-item">
+					<a href={item.path} class="index-link">{item.name}</a>
+				</li>
+			{/each}
+		</ul>
+	</div>
+{:else if data.kind === 'stub'}
+	<div class="stub-page">
+		<p>Start at page 1</p>
+		<a href={data.firstPagePath}>Begin</a>
+	</div>
+{:else if data.kind === 'error'}
+	<div class="error-state">
+		<p class="error-message">{data.message}</p>
+		{#if data.hint}
+			<p class="error-hint">{data.hint}</p>
+		{/if}
+		{#if data.code === 'page_out_of_range'}
+			<a href="./1" class="error-link">Go to first page</a>
+		{/if}
+	</div>
+{/if}
+
+<style>
+	.tutorial-nav {
+		display: flex;
+		justify-content: space-between;
+		margin-top: 3rem;
+		padding-top: 2rem;
+		border-top: 1px solid var(--border-color);
+	}
+
+	.nav-link {
+		color: var(--text-secondary);
+		text-decoration: none;
+	}
+
+	.nav-link:hover {
+		color: var(--text-color);
+	}
+
+	.nav-placeholder {
+		visibility: hidden;
+	}
+
+	.directory-index {
+		max-width: 70ch;
+		margin: 0 auto;
+		padding: 2rem 1rem;
+	}
+
+	.index-list {
+		list-style: none;
+		padding: 0;
+		margin: 2rem 0;
+	}
+
+	.index-item {
+		margin-bottom: 1rem;
+	}
+
+	.index-link {
+		color: var(--text-color);
+		text-decoration: none;
+		font-size: 1.125rem;
+	}
+
+	.index-link:hover {
+		color: var(--text-secondary);
+	}
+
+	.stub-page {
+		max-width: 70ch;
+		margin: 0 auto;
+		padding: 4rem 1rem;
+		text-align: center;
+	}
+
+	.stub-page a {
+		color: var(--text-color);
+		text-decoration: underline;
+	}
+
+	.error-state {
+		max-width: 70ch;
+		margin: 0 auto;
+		padding: 4rem 1rem;
+		text-align: center;
+	}
+
+	.error-message {
+		font-size: 1.125rem;
+		color: var(--text-color);
+		margin-bottom: 1rem;
+	}
+
+	.error-hint {
+		font-size: 1rem;
+		color: var(--text-secondary);
+		margin-bottom: 2rem;
+	}
+
+	.error-link {
+		color: var(--text-color);
+		text-decoration: underline;
+	}
+
+	.error-link:hover {
+		color: var(--text-secondary);
+	}
+</style>
+

package/src/kit/index.d.ts

@@ -0,0 +1,19 @@
+import type { Load, EntryGenerator } from '@sveltejs/kit';
+import Tutorial from './Tutorial.svelte';
+
+export interface TutorialKitOptions {
+	renderMarkdown: (markdown: string) => string | Promise<string>;
+	modules: Record<string, string>;
+	routeBase?: string;
+	enableDirectoryIndex?: boolean;
+}
+
+export interface TutorialKitResult {
+	load: Load;
+	entries: EntryGenerator;
+}
+
+export function tutorialKit(options: TutorialKitOptions): TutorialKitResult;
+
+export { Tutorial };
+

package/src/kit/index.js

@@ -0,0 +1,69 @@
+import { createTutorialLoad } from '../lib/createTutorialLoad.js';
+import { createTutorialEntries } from '../lib/createTutorialEntries.js';
+import Tutorial from './Tutorial.svelte';
+
+/**
+ * Create tutorial load and entries functions with minimal configuration
+ * @param {Object} options
+ * @param {(markdown: string) => string | Promise<string>} options.renderMarkdown - Function to render markdown to HTML
+ * @param {Record<string, string>} options.modules - Map of file paths to file contents (result of import.meta.glob)
+ * @param {string} [options.routeBase='/tutorial'] - Base route path
+ * @param {boolean} [options.enableDirectoryIndex=true] - Enable directory exploration
+ * @returns {{ load: import('@sveltejs/kit').Load, entries: import('@sveltejs/kit').EntryGenerator }}
+ */
+export function tutorialKit({
+	renderMarkdown,
+	modules,
+	routeBase = '/tutorial',
+	enableDirectoryIndex = true,
+}) {
+	if (!renderMarkdown) {
+		// Return load function that always returns error state
+		const errorLoad = async () => ({
+			kind: 'error',
+			code: 'no_renderer',
+			message: 'No markdown renderer is configured.',
+		});
+
+		// Return empty entries
+		const emptyEntries = async () => [];
+
+		return {
+			load: errorLoad,
+			entries: emptyEntries,
+		};
+	}
+
+	if (!modules) {
+		const errorLoad = async () => ({
+			kind: 'error',
+			code: 'no_modules',
+			message: 'Tutorial content modules are not provided. Pass modules from import.meta.glob().',
+		});
+
+		const emptyEntries = async () => [];
+
+		return {
+			load: errorLoad,
+			entries: emptyEntries,
+		};
+	}
+
+	const load = createTutorialLoad({
+		routeBase,
+		modules,
+		renderMarkdown,
+		enableDirectoryIndex,
+	});
+
+	const entries = createTutorialEntries({
+		routeBase,
+		modules,
+		enableDirectoryIndex,
+	});
+
+	return { load, entries };
+}
+
+export { Tutorial };
+

package/src/lib/components/DirectoryIndex.svelte

@@ -0,0 +1,45 @@
+<script>
+	export let data;
+</script>
+
+<div class="directory-index">
+	<h1>Contents</h1>
+	<ul class="index-list">
+		{#each data.items as item}
+			<li class="index-item">
+				<a href={item.path} class="index-link">
+					{item.name}
+				</a>
+			</li>
+		{/each}
+	</ul>
+</div>
+
+<style>
+	.directory-index {
+		max-width: 70ch;
+		margin: 0 auto;
+		padding: 2rem 1rem;
+	}
+
+	.index-list {
+		list-style: none;
+		padding: 0;
+		margin: 2rem 0;
+	}
+
+	.index-item {
+		margin-bottom: 1rem;
+	}
+
+	.index-link {
+		color: var(--text-color, #111827);
+		text-decoration: none;
+		font-size: 1.125rem;
+	}
+
+	.index-link:hover {
+		color: var(--text-secondary, #6b7280);
+	}
+</style>
+

package/src/lib/components/ErrorState.svelte

@@ -0,0 +1,44 @@
+<script>
+	export let data;
+</script>
+
+<div class="error-state">
+	<p class="error-message">{data.message}</p>
+	{#if data.hint}
+		<p class="error-hint">{data.hint}</p>
+	{/if}
+	{#if data.code === 'page_out_of_range'}
+		<a href="./1" class="error-link">Go to first page</a>
+	{/if}
+</div>
+
+<style>
+	.error-state {
+		max-width: 70ch;
+		margin: 0 auto;
+		padding: 4rem 1rem;
+		text-align: center;
+	}
+
+	.error-message {
+		font-size: 1.125rem;
+		color: var(--text-color, #111827);
+		margin-bottom: 1rem;
+	}
+
+	.error-hint {
+		font-size: 1rem;
+		color: var(--text-secondary, #6b7280);
+		margin-bottom: 2rem;
+	}
+
+	.error-link {
+		color: var(--text-color, #111827);
+		text-decoration: underline;
+	}
+
+	.error-link:hover {
+		color: var(--text-secondary, #6b7280);
+	}
+</style>
+

package/src/lib/components/TutorialPage.svelte

@@ -0,0 +1,48 @@
+<script>
+	export let data;
+</script>
+
+<article class="tutorial-page">
+	<h1>{data.title}</h1>
+	<div class="tutorial-content">
+		{@html data.html}
+	</div>
+	<nav class="tutorial-nav">
+		{#if data.nav.previous}
+			<a href={data.nav.previous} class="nav-link nav-previous">Previous</a>
+		{/if}
+		{#if data.nav.next}
+			<a href={data.nav.next} class="nav-link nav-next">Next</a>
+		{/if}
+	</nav>
+</article>
+
+<style>
+	.tutorial-page {
+		max-width: 70ch;
+		margin: 0 auto;
+		padding: 2rem 1rem;
+	}
+
+	.tutorial-content {
+		margin: 2rem 0;
+	}
+
+	.tutorial-nav {
+		display: flex;
+		justify-content: space-between;
+		margin-top: 3rem;
+		padding-top: 2rem;
+		border-top: 1px solid var(--border-color, #e5e7eb);
+	}
+
+	.nav-link {
+		color: var(--text-secondary, #6b7280);
+		text-decoration: none;
+	}
+
+	.nav-link:hover {
+		color: var(--text-color, #111827);
+	}
+</style>
+

package/src/lib/createTutorialEntries.js

@@ -0,0 +1,21 @@
+import { generateEntries } from './routes.js';
+
+/**
+ * Create a SvelteKit entries function for SSG
+ * @param {Object} options
+ * @param {string} options.routeBase - Base route path (e.g., '/tutorial')
+ * @param {Record<string, any>} options.modules - Result of import.meta.glob() from host
+ * @param {boolean} [options.enableDirectoryIndex=true] - Enable directory exploration
+ * @returns {import('@sveltejs/kit').EntryGenerator}
+ */
+export function createTutorialEntries({ routeBase, modules, enableDirectoryIndex = true }) {
+	if (!modules) {
+		throw new Error('modules is required');
+	}
+
+	return async () => {
+		const entries = generateEntries(modules, routeBase, enableDirectoryIndex);
+		return entries;
+	};
+}
+

package/src/lib/createTutorialLoad.js

@@ -0,0 +1,215 @@
+import { resolveRoute } from './routes.js';
+import { parseSegment } from './parse.js';
+import { getNavigation } from './navigation.js';
+import { discoverContent } from './discover.js';
+
+/**
+ * Create a SvelteKit load function for tutorial routes
+ * @param {Object} options
+ * @param {string} options.routeBase - Base route path (e.g., '/tutorial')
+ * @param {Record<string, any>} options.modules - Result of import.meta.glob() from host
+ * @param {(markdown: string) => string | Promise<string>} options.renderMarkdown - Function to render markdown to HTML
+ * @param {boolean} [options.enableDirectoryIndex=true] - Enable directory exploration
+ * @returns {import('@sveltejs/kit').Load}
+ */
+export function createTutorialLoad({ routeBase, modules, renderMarkdown, enableDirectoryIndex = true }) {
+	if (!renderMarkdown) {
+		throw new Error('renderMarkdown is required');
+	}
+
+	if (!modules) {
+		throw new Error('modules is required');
+	}
+
+	return async ({ params }) => {
+		// Handle catch-all route - path might be a string or array
+		// If it's a string, split it into segments
+		const pathParam = params.path;
+		const pathArray = Array.isArray(pathParam)
+			? pathParam
+			: typeof pathParam === 'string'
+				? pathParam.split('/').filter(Boolean)
+				: [];
+		
+		// Debug logging
+		if (process.env.NODE_ENV === 'development') {
+			console.log('[tutorial-svelte] pathArray:', pathArray);
+			console.log('[tutorial-svelte] modules keys:', Object.keys(modules));
+			const discovered = discoverContent(modules);
+			console.log('[tutorial-svelte] discovered:', discovered);
+		}
+		
+		const resolved = resolveRoute(pathArray, modules, routeBase);
+		
+		if (process.env.NODE_ENV === 'development') {
+			console.log('[tutorial-svelte] resolved:', resolved);
+		}
+
+		// Handle error case (not found)
+		if (resolved.type === 'error') {
+			const discovered = discoverContent(modules);
+			if (process.env.NODE_ENV === 'development') {
+				console.log('[tutorial-svelte] Path not found. Looking for:', pathArray.join('/'));
+				console.log('[tutorial-svelte] Available routes:', discovered.map(d => d.routePath));
+			}
+			return {
+				kind: 'error',
+				code: 'not_found',
+				message: 'That page doesn\'t exist.',
+			};
+		}
+
+		// Handle page route
+		if (resolved.type === 'page') {
+			const module = modules[resolved.filePath];
+			let content = '';
+
+			// Handle different module formats (eager vs lazy loading)
+			if (typeof module === 'function') {
+				// Lazy-loaded module - await it
+				const loaded = await module();
+				content = typeof loaded === 'string' ? loaded : loaded?.default || String(loaded?.default || '');
+			} else if (typeof module === 'string') {
+				content = module;
+			} else if (module?.default) {
+				content = typeof module.default === 'string' ? module.default : String(module.default);
+			} else if (typeof module === 'object' && 'default' in module) {
+				content = String(module.default);
+			}
+
+			const { pages, hasH1 } = parseSegment(content);
+
+			if (!hasH1 || 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.',
+				};
+			}
+
+			if (resolved.pageNum < 1 || resolved.pageNum > pages.length) {
+				return {
+					kind: 'error',
+					code: 'page_out_of_range',
+					message: 'That page doesn\'t exist.',
+					hint: 'Try the first page.',
+				};
+			}
+
+			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
+			let contentToRender = page.content;
+			const lines = contentToRender.split('\n');
+			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);
+
+			const nav = getNavigation(resolved.segmentPath, resolved.pageNum, pages.length, routeBase);
+
+			return {
+				kind: 'page',
+				html,
+				title: page.title,
+				page: resolved.pageNum,
+				totalPages: pages.length,
+				nav,
+				segmentPath: resolved.segmentPath,
+			};
+		}
+
+		// Handle stub route (segment root)
+		if (resolved.type === 'stub') {
+			const firstPagePath = `${routeBase}/${resolved.segmentPath}/1`;
+			return {
+				kind: 'stub',
+				segmentPath: resolved.segmentPath,
+				firstPagePath,
+			};
+		}
+
+		// Handle directory index
+		if (resolved.type === 'index') {
+			if (!enableDirectoryIndex) {
+				return {
+					kind: 'error',
+					code: 'directory_disabled',
+					message: 'Directory exploration is disabled for this tutorial.',
+				};
+			}
+
+			const discovered = discoverContent(modules);
+			const directoryPath = resolved.directoryPath || '';
+			const items = [];
+			const children = new Map(); // name -> { type: 'segment' | 'directory', path: string }
+
+			// Find all direct children (segments and subdirectories)
+			for (const item of discovered) {
+				const routeParts = item.routePath.split('/');
+				const dirParts = directoryPath ? directoryPath.split('/') : [];
+
+				// Check if this item is a direct child of the directory
+				if (routeParts.length === dirParts.length + 1) {
+					// Direct child segment
+					if (
+						dirParts.length === 0 ||
+						routeParts.slice(0, dirParts.length).join('/') === directoryPath
+					) {
+						const segmentName = routeParts[dirParts.length];
+						children.set(segmentName, {
+							type: 'segment',
+							path: item.routePath,
+						});
+					}
+				} else if (routeParts.length > dirParts.length + 1) {
+					// Potential subdirectory
+					if (
+						dirParts.length === 0 ||
+						routeParts.slice(0, dirParts.length).join('/') === directoryPath
+					) {
+						const subdirName = routeParts[dirParts.length];
+						// Only add if we haven't seen it as a segment
+						if (!children.has(subdirName)) {
+							children.set(subdirName, {
+								type: 'directory',
+								path: routeParts.slice(0, dirParts.length + 1).join('/'),
+							});
+						}
+					}
+				}
+			}
+
+			// Build items list
+			for (const [childName, info] of Array.from(children.entries()).sort()) {
+				if (info.type === 'segment') {
+					items.push({
+						name: childName,
+						path: `${routeBase}/${info.path}/1`,
+						type: 'segment',
+					});
+				} else {
+					items.push({
+						name: childName,
+						path: `${routeBase}/${info.path}`,
+						type: 'directory',
+					});
+				}
+			}
+
+			return {
+				kind: 'index',
+				items,
+				path: directoryPath || '',
+			};
+		}
+
+		// Fallback error
+		return {
+			kind: 'error',
+			code: 'unknown',
+			message: 'An unexpected error occurred.',
+		};
+	};
+}
+

package/src/lib/discover.js

@@ -0,0 +1,69 @@
+/**
+ * Process modules from import.meta.glob() to discover markdown files
+ * @param {Record<string, any>} modules - Result of import.meta.glob() from host
+ * @returns {Array<{ filePath: string, routePath: string }>}
+ */
+export function discoverContent(modules) {
+	const discovered = [];
+	const filePaths = Object.keys(modules);
+
+	if (filePaths.length === 0) {
+		return discovered;
+	}
+
+	// Find the content root directory by detecting common patterns
+	// Look for '/src/content/', '/src/tutorials/', '/content/', or '/tutorials/' in paths
+	// This ensures we preserve the directory structure
+	let commonPrefix = '/src/content/';
+	
+	// Check common patterns in order of preference
+	if (filePaths.every(path => path.includes('/src/content/'))) {
+		commonPrefix = '/src/content/';
+	} else if (filePaths.every(path => path.includes('/src/tutorials/'))) {
+		commonPrefix = '/src/tutorials/';
+	} else if (filePaths.every(path => path.includes('/content/'))) {
+		commonPrefix = '/content/';
+	} else if (filePaths.every(path => path.includes('/tutorials/'))) {
+		commonPrefix = '/tutorials/';
+	} else {
+		// Fallback: find longest common prefix
+		// This handles any other directory structure
+		commonPrefix = filePaths[0];
+		for (const path of filePaths) {
+			while (!path.startsWith(commonPrefix)) {
+				const lastSlash = commonPrefix.lastIndexOf('/');
+				if (lastSlash === -1) break;
+				commonPrefix = commonPrefix.slice(0, lastSlash + 1);
+			}
+		}
+		if (!commonPrefix.endsWith('/')) {
+			commonPrefix = commonPrefix.slice(0, commonPrefix.lastIndexOf('/') + 1);
+		}
+	}
+	
+	// Debug: log the common prefix to verify it's correct
+	// Note: In browser context, we can't use process.env, so skip debug logging here
+
+	// Now extract route paths - remove the common prefix and .md extension
+	// Keep the full directory structure relative to the content root
+	for (const [filePath, module] of Object.entries(modules)) {
+		let routePath = filePath;
+		
+		// Remove the common prefix (e.g., '/src/content/')
+		if (routePath.startsWith(commonPrefix)) {
+			routePath = routePath.slice(commonPrefix.length);
+		}
+		
+		// Remove .md extension and leading/trailing slashes
+		// Keep the directory structure (e.g., "greenhouse/arc1/intro")
+		routePath = routePath.replace(/\.md$/, '').replace(/^\/+/, '').replace(/\/+$/, '');
+
+		discovered.push({
+			filePath,
+			routePath,
+		});
+	}
+
+	return discovered;
+}
+

package/src/lib/navigation.js

@@ -0,0 +1,16 @@
+/**
+ * Calculate next/previous page navigation within a segment
+ * @param {string} segmentPath - Path to the segment (e.g., 'greenhouse/arc1/intro')
+ * @param {number} currentPage - Current page number (1-indexed)
+ * @param {number} totalPages - Total number of pages in segment
+ * @param {string} routeBase - Base route path (e.g., '/tutorial')
+ * @returns {{ previous: string | null, next: string | null }}
+ */
+export function getNavigation(segmentPath, currentPage, totalPages, routeBase) {
+	const basePath = `${routeBase}/${segmentPath}`;
+	const previous = currentPage > 1 ? `${basePath}/${currentPage - 1}` : null;
+	const next = currentPage < totalPages ? `${basePath}/${currentPage + 1}` : null;
+
+	return { previous, next };
+}
+

package/src/lib/parse.js

@@ -0,0 +1,63 @@
+/**
+ * Split markdown content on H1 headings (# )
+ * Ignores H1 headings inside fenced code blocks (```)
+ * @param {string} markdownContent - Raw markdown content
+ * @returns {{ pages: Array<{ title: string, content: string }>, hasH1: boolean }}
+ */
+export function parseSegment(markdownContent) {
+	const lines = markdownContent.split('\n');
+	const pages = [];
+	let currentPage = null;
+	let hasH1 = false;
+	let inCodeBlock = false;
+
+	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
+			inCodeBlock = !inCodeBlock;
+		}
+
+		// Only check for H1 if we're not inside a code block
+		if (!inCodeBlock && trimmed.startsWith('# ') && !trimmed.startsWith('##')) {
+			hasH1 = true;
+
+			// 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();
+
+			// Start new page
+			currentPage = {
+				title,
+				content: line + '\n',
+			};
+		} else if (currentPage !== null) {
+			// Add line to current page content
+			currentPage.content += line + '\n';
+		}
+	}
+
+	// Don't forget the last page
+	if (currentPage !== null) {
+		pages.push(currentPage);
+	}
+
+	// Trim trailing newlines from content
+	pages.forEach((page) => {
+		page.content = page.content.trimEnd();
+	});
+
+	return {
+		pages,
+		hasH1,
+	};
+}
+

package/src/lib/routes.js

@@ -0,0 +1,152 @@
+import { discoverContent } from './discover.js';
+import { parseSegment } from './parse.js';
+
+/**
+ * Resolve URL path segments to determine route type and extract metadata
+ * @param {string[]} pathArray - URL path segments (e.g., ['greenhouse', 'arc1', 'intro', '1'])
+ * @param {Record<string, any>} modules - Modules from import.meta.glob()
+ * @param {string} routeBase - Base route path
+ * @returns {{ type: 'page' | 'stub' | 'index' | 'error', segmentPath?: string, pageNum?: number, filePath?: string, directoryPath?: string }}
+ */
+export function resolveRoute(pathArray, modules, routeBase) {
+	if (pathArray.length === 0) {
+		return { type: 'error' };
+	}
+
+	const discovered = discoverContent(modules);
+
+	// Check if last segment is a number (page number)
+	const lastSegment = pathArray[pathArray.length - 1];
+	const pageNum = parseInt(lastSegment, 10);
+
+	// If last segment is a valid page number, it's a page route
+	if (!isNaN(pageNum) && pageNum > 0) {
+		// Segment path is everything except the page number
+		const segmentPath = pathArray.slice(0, -1).join('/');
+		const routePath = segmentPath;
+
+		// Find matching file
+		const match = discovered.find((d) => d.routePath === routePath);
+		if (match) {
+			return {
+				type: 'page',
+				segmentPath,
+				pageNum,
+				filePath: match.filePath,
+			};
+		}
+
+		return { type: 'error' };
+	}
+
+	// Check if it's a segment root (ends with a segment name, not a directory)
+	const potentialSegmentPath = pathArray.join('/');
+	const segmentMatch = discovered.find((d) => d.routePath === potentialSegmentPath);
+
+	if (segmentMatch) {
+		// It's a segment root - return stub
+		return {
+			type: 'stub',
+			segmentPath: potentialSegmentPath,
+			filePath: segmentMatch.filePath,
+		};
+	}
+
+	// Check if it's a directory (has child segments or subdirectories)
+	const directoryPath = pathArray.join('/');
+	const hasChildren = discovered.some((d) => {
+		const routeParts = d.routePath.split('/');
+		const dirParts = directoryPath.split('/');
+		return (
+			routeParts.length > dirParts.length &&
+			routeParts.slice(0, dirParts.length).join('/') === directoryPath
+		);
+	});
+
+	if (hasChildren) {
+		return {
+			type: 'index',
+			directoryPath,
+		};
+	}
+
+	// Not found
+	return { type: 'error' };
+}
+
+/**
+ * Generate all SSG entries for tutorial routes
+ * @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[] }>}
+ */
+export function generateEntries(modules, routeBase, enableDirectoryIndex) {
+	const entries = [];
+	const discovered = discoverContent(modules);
+
+	// Generate entries for all pages of all segments
+	for (const item of discovered) {
+		// Get markdown content to count pages
+		const module = modules[item.filePath];
+		let content = '';
+
+		// Handle different module formats
+		// Note: For SSG, use eager: true in import.meta.glob() for best performance
+		if (typeof module === 'function') {
+			// Lazy-loaded module - skip for entries generation
+			// For SSG, use eager: true to avoid async complexity
+			continue;
+		} else if (typeof module === 'string') {
+			content = module;
+		} else if (module?.default) {
+			content = typeof module.default === 'string' ? module.default : String(module.default);
+		} else if (typeof module === 'object' && 'default' in module) {
+			content = String(module.default);
+		}
+
+		const { pages, hasH1 } = parseSegment(content);
+
+		if (!hasH1 || pages.length === 0) {
+			// Skip files with no H1 headings
+			continue;
+		}
+
+		const segmentPathParts = item.routePath.split('/');
+
+		// Generate entry for each page
+		for (let pageNum = 1; pageNum <= pages.length; pageNum++) {
+			entries.push({
+				path: [...segmentPathParts, String(pageNum)],
+			});
+		}
+
+		// Generate stub entry for segment root
+		entries.push({
+			path: segmentPathParts,
+		});
+
+		// Generate directory index entries if enabled
+		if (enableDirectoryIndex) {
+			// Generate entries for all parent directories
+			for (let i = 1; i < segmentPathParts.length; i++) {
+				const dirPath = segmentPathParts.slice(0, i);
+				const dirPathStr = dirPath.join('/');
+
+				// Check if we've already added this directory
+				const exists = entries.some(
+					(e) => e.path.length === dirPath.length && e.path.join('/') === dirPathStr
+				);
+
+				if (!exists) {
+					entries.push({
+						path: dirPath,
+					});
+				}
+			}
+		}
+	}
+
+	return entries;
+}
+