Merge pull request #3 from pathsim/feature/example-thumbnails

example thumbnails

Author: milanofthe

scripts/lib/notebooks.py

@@ -79,6 +79,7 @@ def _process_notebook(nb_path: Path, output_dir: Path) -> dict | None:
     # Extract metadata
     title = _extract_title(notebook)
     description = _extract_description(notebook)
+    thumbnail_path = _extract_thumbnail(notebook)
 
     # Get category and tags from mapping
     category, tags = CATEGORY_MAPPINGS.get(stem, ("advanced", []))
@@ -92,7 +93,24 @@ def _process_notebook(nb_path: Path, output_dir: Path) -> dict | None:
     with open(output_path, "w", encoding="utf-8") as f:
         json.dump(clean_notebook, f, indent=1, ensure_ascii=False)
 
-    return {
+    # Process thumbnail path - convert to figures-relative path
+    thumbnail = None
+    if thumbnail_path:
+        # Handle relative paths like "../figures/image.png" or "figures/image.png"
+        # Extract just the filename or subdirectory/filename
+        path_parts = Path(thumbnail_path.replace("\\", "/"))
+        # Get the path relative to figures directory
+        # Common patterns: ../figures/foo.png, figures/foo.png, ./figures/foo.png
+        parts = path_parts.parts
+        if "figures" in parts:
+            # Find index of 'figures' and take everything after
+            fig_idx = parts.index("figures")
+            thumbnail = "/".join(parts[fig_idx + 1:])
+        else:
+            # Just use the filename
+            thumbnail = path_parts.name
+
+    result = {
         "slug": slug,
         "file": nb_path.name,
         "title": title,
@@ -102,6 +120,11 @@ def _process_notebook(nb_path: Path, output_dir: Path) -> dict | None:
         "executable": executable,
     }
 
+    if thumbnail:
+        result["thumbnail"] = thumbnail
+
+    return result
+
 
 def _strip_outputs(notebook: dict) -> dict:
     """Remove outputs from notebook cells (keep source only)."""
@@ -138,6 +161,49 @@ def _extract_title(notebook: dict) -> str:
     return "Untitled"
 
 
+def _extract_thumbnail(notebook: dict) -> str | None:
+    """Extract first image path from markdown cells.
+
+    Looks for images in markdown cells using:
+    - Markdown syntax: ![alt](path)
+    - HTML syntax: <img src="path">
+    - RST syntax: .. image:: path
+
+    Returns the image path (relative to notebook) or None if not found.
+    """
+    # Pattern for markdown images: ![alt](path)
+    md_pattern = re.compile(r'!\[[^\]]*\]\(([^)]+)\)')
+    # Pattern for HTML images: <img src="path"> or <img src='path'>
+    html_pattern = re.compile(r'<img[^>]+src=["\']([^"\']+)["\']', re.IGNORECASE)
+    # Pattern for RST images: .. image:: path
+    rst_pattern = re.compile(r'\.\.\s+image::\s*(\S+)')
+
+    for cell in notebook.get("cells", []):
+        cell_type = cell.get("cell_type")
+        # Check markdown and raw cells (RST is often in raw cells)
+        if cell_type in ("markdown", "raw"):
+            source = cell.get("source", [])
+            if isinstance(source, list):
+                source = "".join(source)
+
+            # Try markdown syntax first
+            match = md_pattern.search(source)
+            if match:
+                return match.group(1)
+
+            # Try HTML syntax
+            match = html_pattern.search(source)
+            if match:
+                return match.group(1)
+
+            # Try RST syntax
+            match = rst_pattern.search(source)
+            if match:
+                return match.group(1)
+
+    return None
+
+
 def _extract_description(notebook: dict) -> str:
     """Extract description from first paragraph after title.
 

scripts/rebuild-manifests.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""
+Rebuild manifest.json files with updated metadata (e.g., thumbnails).
+Does not re-execute notebooks - just re-extracts metadata from existing notebooks.
+"""
+
+import json
+from pathlib import Path
+
+from lib.notebooks import (
+    _extract_title,
+    _extract_description,
+    _extract_thumbnail,
+    _slugify,
+    generate_version_manifest,
+)
+from lib.config import CATEGORY_MAPPINGS, NON_EXECUTABLE
+
+
+def rebuild_manifest(version_dir: Path) -> bool:
+    """Rebuild manifest.json for a version directory."""
+    notebooks_dir = version_dir / "notebooks"
+    manifest_path = version_dir / "manifest.json"
+
+    if not notebooks_dir.exists() or not manifest_path.exists():
+        return False
+
+    # Load existing manifest to get package and tag
+    with open(manifest_path, "r", encoding="utf-8") as f:
+        existing = json.load(f)
+
+    package_id = existing.get("package", version_dir.parent.name)
+    tag = existing.get("tag", version_dir.name)
+
+    print(f"  Rebuilding {package_id}/{tag}...")
+
+    # Re-extract metadata from all notebooks
+    notebooks = []
+    for nb_path in sorted(notebooks_dir.glob("*.ipynb")):
+        try:
+            with open(nb_path, "r", encoding="utf-8") as f:
+                notebook = json.load(f)
+
+            stem = nb_path.stem
+            slug = _slugify(stem)
+
+            # Extract metadata
+            title = _extract_title(notebook)
+            description = _extract_description(notebook)
+            thumbnail_path = _extract_thumbnail(notebook)
+
+            # Get category and tags from mapping
+            category, tags = CATEGORY_MAPPINGS.get(stem, ("advanced", []))
+
+            # Check if executable
+            executable = stem not in NON_EXECUTABLE
+
+            # Process thumbnail path
+            thumbnail = None
+            if thumbnail_path:
+                path_parts = Path(thumbnail_path.replace("\\", "/"))
+                parts = path_parts.parts
+                if "figures" in parts:
+                    fig_idx = parts.index("figures")
+                    thumbnail = "/".join(parts[fig_idx + 1:])
+                else:
+                    thumbnail = path_parts.name
+
+            meta = {
+                "slug": slug,
+                "file": nb_path.name,
+                "title": title,
+                "description": description,
+                "category": category,
+                "tags": tags,
+                "executable": executable,
+            }
+
+            if thumbnail:
+                meta["thumbnail"] = thumbnail
+                print(f"    {nb_path.name}: thumbnail = {thumbnail}")
+
+            notebooks.append(meta)
+
+        except Exception as e:
+            print(f"    Warning: Failed to process {nb_path.name}: {e}")
+
+    # Generate and save new manifest
+    manifest = generate_version_manifest(package_id, tag, notebooks)
+    with open(manifest_path, "w", encoding="utf-8") as f:
+        json.dump(manifest, f, indent=2, ensure_ascii=False)
+
+    return True
+
+
+def main():
+    static_dir = Path(__file__).parent.parent / "static"
+
+    print("Rebuilding manifests...")
+
+    # Find all package directories
+    for package_dir in static_dir.iterdir():
+        if not package_dir.is_dir():
+            continue
+
+        # Skip non-package directories
+        if package_dir.name.startswith("."):
+            continue
+
+        print(f"\nPackage: {package_dir.name}")
+
+        # Find all version directories
+        for version_dir in package_dir.iterdir():
+            if not version_dir.is_dir():
+                continue
+            if not version_dir.name.startswith("v"):
+                continue
+
+            rebuild_manifest(version_dir)
+
+    print("\nDone!")
+
+
+if __name__ == "__main__":
+    main()

src/lib/notebook/manifest.ts

@@ -24,6 +24,8 @@ export interface NotebookMeta {
 	tags: string[];
 	/** Whether notebook can run in Pyodide */
 	executable: boolean;
+	/** Thumbnail image filename (relative to figures directory) */
+	thumbnail?: string;
 }
 
 export interface Category {

src/routes/+layout.svelte

@@ -3,6 +3,7 @@
 	import { onMount } from 'svelte';
 	import { base } from '$app/paths';
 	import { page } from '$app/stores';
+	import { afterNavigate } from '$app/navigation';
 	import Tooltip from '$lib/components/common/Tooltip.svelte';
 	import { Header, MobileDrawer } from '$lib/components/layout';
 	import { packageOrder, type PackageId } from '$lib/config/packages';
@@ -85,6 +86,19 @@
 		$page.url.pathname;
 		mobileMenuOpen = false;
 	});
+
+	// Scroll to top on navigation
+	afterNavigate(() => {
+		// Find scrollable content areas and reset their scroll position
+		const scrollables = document.querySelectorAll('.doc-main, .page-wrapper');
+		scrollables.forEach((el) => {
+			if (el instanceof HTMLElement) {
+				el.scrollTop = 0;
+			}
+		});
+		// Also reset window scroll as fallback
+		window.scrollTo(0, 0);
+	});
 </script>
 
 <svelte:head>

src/routes/[package]/[version]/examples/+page.svelte

@@ -43,6 +43,10 @@
 	function navigateToExample(slug: string) {
 		goto(`${base}/${data.packageId}/${data.resolvedTag}/examples/${slug}`);
 	}
+
+	function getThumbnailUrl(thumbnail: string): string {
+		return `${base}/${data.packageId}/${data.resolvedTag}/figures/${thumbnail}`;
+	}
 </script>
 
 <svelte:head>
@@ -61,7 +65,7 @@
 	{#each [...groupedNotebooks] as [category, notebooks]}
 		<h2 id={category.id}>{category.title}</h2>
 
-		<div class="tile-grid cols-3">
+		<div class="tile-grid cols-2">
 			{#each notebooks as notebook}
 				<div
 					class="tile example-tile elevated"
@@ -71,7 +75,14 @@
 					tabindex="0"
 				>
 					<div class="panel-header">{notebook.title}</div>
-					<div class="panel-body tile-body">{notebook.description}</div>
+					<div class="panel-body tile-body">
+						<p class="tile-description">{notebook.description}</p>
+						{#if notebook.thumbnail}
+							<div class="thumbnail-wrapper">
+								<img src={getThumbnailUrl(notebook.thumbnail)} alt={notebook.title} />
+							</div>
+						{/if}
+					</div>
 				</div>
 			{/each}
 		</div>
@@ -93,4 +104,29 @@
 	.example-tile {
 		cursor: pointer;
 	}
+
+	/* Tile description text */
+	.tile-description {
+		margin: 0 0 var(--space-md) 0;
+		color: var(--text-muted);
+		font-size: var(--font-sm);
+		line-height: 1.5;
+	}
+
+	/* Thumbnail wrapper and image */
+	.thumbnail-wrapper {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		overflow: hidden;
+	}
+
+	.thumbnail-wrapper img {
+		max-width: 100%;
+		max-height: 180px;
+		width: auto;
+		height: auto;
+		object-fit: contain;
+		border-radius: var(--radius-sm);
+	}
 </style>