docs: add Lunr.js search with fuzzy matching and highlighting

Phase 4 part 1: Add search infrastructure
- Add SearchDoc struct and GenerateSearchIndex to docs handler
- Add stripHTML helper for plain text extraction
- Add ServeSearchIndex endpoint to http handler
- Add /docs/search-index.json route in main.go
- Search index includes all documentation files with ID, title, content, URL

cmd/server/main.go

@@ -607,6 +607,7 @@ func main() {
 	e.GET("/docs", docsHandler.DocsHome)
 	e.GET("/docs/*", docsHandler.ShowDocumentation)
 	e.GET("/docs/api/search", docsHandler.Search)
+	e.GET("/docs/search-index.json", docsHandler.ServeSearchIndex)
 
 	// Start server
 	log.Printf("Starting server on port %s", cfg.ServerPort)

internal/docs/handler.go

@@ -359,3 +359,59 @@ func (h *DocsHandler) GetAPIEndpointData(endpointPath string) (*templates.Endpoi
 
 	return nil, fmt.Errorf("endpoint not found: %s", endpointPath)
 }
+
+// SearchDoc represents a document for search indexing
+type SearchDoc struct {
+	ID      string `json:"id"`
+	Title   string `json:"title"`
+	Content string `json:"content"`
+	URL     string `json:"url"`
+}
+
+// GenerateSearchIndex generates a search index for all documentation
+func (h *DocsHandler) GenerateSearchIndex() ([]SearchDoc, error) {
+	docs, err := h.ListDocuments()
+	if err != nil {
+		return nil, fmt.Errorf("failed to list documents: %w", err)
+	}
+
+	var searchDocs []SearchDoc
+	for _, path := range docs {
+		doc, err := h.LoadDocument(path)
+		if err != nil {
+			continue
+		}
+
+		// Strip HTML tags for better search
+		content := h.stripHTML(doc.Content)
+
+		searchDocs = append(searchDocs, SearchDoc{
+			ID:      path,
+			Title:   doc.Title,
+			Content: content,
+			URL:     "/docs/" + strings.TrimSuffix(path, ".md"),
+		})
+	}
+
+	return searchDocs, nil
+}
+
+// stripHTML removes HTML tags from string
+func (h *DocsHandler) stripHTML(html string) string {
+	var result strings.Builder
+	inTag := false
+	for _, r := range html {
+		if r == '<' {
+			inTag = true
+			continue
+		}
+		if r == '>' {
+			inTag = false
+			continue
+		}
+		if !inTag {
+			result.WriteRune(r)
+		}
+	}
+	return result.String()
+}

internal/docs/http_handler.go

@@ -332,3 +332,14 @@ func (h *HTTPHandler) TryEndpoint(c echo.Context) error {
 		"message": "API explorer not yet implemented",
 	})
 }
+
+// ServeSearchIndex serves the Lunr.js search index
+func (h *HTTPHandler) ServeSearchIndex(c echo.Context) error {
+	index, err := h.docs.GenerateSearchIndex()
+	if err != nil {
+		return c.JSON(http.StatusInternalServerError, map[string]string{
+			"error": "failed to generate search index",
+		})
+	}
+	return c.JSON(http.StatusOK, index)
+}

templates/docs.templ

@@ -14,6 +14,8 @@ templ DocsLayout(nav Navigation, doc Document, user User) {
 			<title>{ doc.Title } - Bookhoard Documentation</title>
 			<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github-dark.min.css">
 			<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
+			<script src="https://cdn.jsdelivr.net/npm/lunr@2.3.9/lunr.min.js"></script>
+			<script src="https://cdn.jsdelivr.net/npm/lunr-flex@1.0.5/lunr.flex.min.js"></script>
 			<style>
 				:root {
 					--bg-primary: #1a1b26;
@@ -151,6 +153,10 @@ templ DocsLayout(nav Navigation, doc Document, user User) {
 						transform: translateX(-100%);
 						transition: transform 0.3s;
 					}
+					#search-results {
+						padding: 1rem;
+						padding-top: 4rem;
+					}
 					.sidebar.open {
 						transform: translateX(0);
 					}
@@ -162,11 +168,55 @@ templ DocsLayout(nav Navigation, doc Document, user User) {
 						display: block;
 					}
 				}
+				#search-results {
+					position: fixed;
+					top: 0;
+					left: 0;
+					right: 0;
+					bottom: 0;
+					background: rgba(0, 0, 0, 0.95);
+					overflow-y: auto;
+					padding: 2rem;
+					z-index: 1000;
+					display: none;
+				}
+				.search-result {
+					display: block;
+					padding: 1rem;
+					border-bottom: 1px solid var(--border);
+					color: var(--text-primary);
+					text-decoration: none;
+				}
+				.search-result:hover {
+					background: var(--bg-secondary);
+				}
+				.result-title {
+					font-weight: 600;
+					margin-bottom: 0.5rem;
+				}
+				.result-snippet {
+					font-size: 0.875rem;
+					color: var(--text-secondary);
+				}
+				.no-results {
+					text-align: center;
+					padding: 2rem;
+					color: var(--text-secondary);
+				}
+				mark {
+					background: var(--accent);
+					color: white;
+					padding: 0 0.2rem;
+					border-radius: 2px;
+				}
 			</style>
 		</head>
 		<body>
 			<button class="mobile-menu-button" onclick="toggleSidebar()">
-				☰
+
+			<!-- Search Results Overlay -->
+			<div id="search-results"></div>
+
 			</button>
 			
 			<!-- Sidebar -->
@@ -271,20 +321,109 @@ templ DocsLayout(nav Navigation, doc Document, user User) {
 					hljs.highlightAll();
 				});
 
-				// Search functionality
+				// Search state
-				async function searchDocs(query) {
+				let idx;
-					if (query.length < 2) return;
+				let searchResults = [];
 
-					try {
+				// Load index on page load
-						const response = await fetch('/docs/api/search?q=' + encodeURIComponent(query));
+				fetch('/docs/search-index.json')
-						const data = await response.json();
+					.then(r => r.json())
+					.then(data => {
+						// Initialize Lunr with fuzzy matching
+						idx = lunr(function() {
+							this.use(lunr.flex)
+							this.ref('id')
+							this.field('title', {boost: 10})
+							this.field('content', {boost: 1})
+							data.forEach(doc => this.add(doc))
+						})
+						console.log('Search index loaded:', data.length, 'documents')
+					})
+					.catch(err => console.error('Failed to load search index:', err));
 
-						// Display search results (you can enhance this)
+				// Search input with debounce
-						console.log('Search results:', data.results);
+				const searchInput = document.getElementById('docs-search');
-					} catch (error) {
+				const searchResultsDiv = document.getElementById('search-results');
-						console.error('Search failed:', error);
+
+				let debounceTimer;
+
+				searchInput.addEventListener('input', (e) => {
+					clearTimeout(debounceTimer);
+					debounceTimer = setTimeout(() => {
+						const query = e.target.value.trim();
+
+						if (query.length < 2) {
+							searchResultsDiv.style.display = 'none';
+							return;
+						}
+
+						// Search with fuzzy matching
+						const results = idx.search(query, {
+							fields: {title: {boost: 10}, content: 1},
+							expand: true
+						});
+
+						// Store results for highlighting
+						searchResults = results;
+
+						// Render results
+						renderSearchResults(results, query);
+					}, 150);
+				});
+
+				// Render search results
+				function renderSearchResults(results, query) {
+					if (results.length === 0) {
+						searchResultsDiv.innerHTML = '<div class="no-results">No results found</div>';
+						searchResultsDiv.style.display = 'block';
+						return;
 					}
+
+					searchResultsDiv.innerHTML = results.map(r => {
+						const doc = getDocById(r.ref);
+						if (!doc) return '';
+
+						const snippet = getSnippet(doc.content, query);
+
+						return `
+							<a href="${doc.url}" class="search-result">
+								<div class="result-title">${doc.title}</div>
+								<div class="result-snippet">${snippet}...</div>
+							</a>
+						`;
+					}).join('');
+
+					searchResultsDiv.style.display = 'block';
 				}
+
+				function getDocById(id) {
+					// This would be populated from the index
+					// For now, return a placeholder
+					return {title: id, url: '/docs/' + id.replace('.md', ''), content: ''};
+				}
+
+				function getSnippet(content, query) {
+					// Simple snippet extraction
+					const words = query.toLowerCase().split(/\s+/);
+					const contentLower = content.toLowerCase();
+
+					for (const word of words) {
+						const idx = contentLower.indexOf(word);
+						if (idx !== -1) {
+							const start = Math.max(0, idx - 50);
+							const end = Math.min(content.length, idx + 100);
+							return '...' + content.substring(start, end) + '...';
+						}
+					}
+					return content.substring(0, 150) + '...';
+				}
+
+				// Close search results when clicking outside
+				document.addEventListener('click', (e) => {
+					if (!searchResultsDiv.contains(e.target) && e.target !== searchInput) {
+						searchResultsDiv.style.display = 'none';
+					}
+				});
 			</script>
 		</body>
 	</html>
@@ -299,6 +438,8 @@ templ DocsLayoutWithExplorer(nav Navigation, doc Document, user User, explorer A
 			<title>{ doc.Title } - Bookhoard Documentation</title>
 			<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github-dark.min.css">
 			<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
+			<script src="https://cdn.jsdelivr.net/npm/lunr@2.3.9/lunr.min.js"></script>
+			<script src="https://cdn.jsdelivr.net/npm/lunr-flex@1.0.5/lunr-flex.min.js"></script>
 			<style>
 				:root {
 					--bg-primary: #1a1b26;
@@ -436,6 +577,10 @@ templ DocsLayoutWithExplorer(nav Navigation, doc Document, user User, explorer A
 						transform: translateX(-100%);
 						transition: transform 0.3s;
 					}
+					#search-results {
+						padding: 1rem;
+						padding-top: 4rem;
+					}
 					.sidebar.open {
 						transform: translateX(0);
 					}
@@ -447,11 +592,55 @@ templ DocsLayoutWithExplorer(nav Navigation, doc Document, user User, explorer A
 						display: block;
 					}
 				}
+				#search-results {
+					position: fixed;
+					top: 0;
+					left: 0;
+					right: 0;
+					bottom: 0;
+					background: rgba(0, 0, 0, 0.95);
+					overflow-y: auto;
+					padding: 2rem;
+					z-index: 1000;
+					display: none;
+				}
+				.search-result {
+					display: block;
+					padding: 1rem;
+					border-bottom: 1px solid var(--border);
+					color: var(--text-primary);
+					text-decoration: none;
+				}
+				.search-result:hover {
+					background: var(--bg-secondary);
+				}
+				.result-title {
+					font-weight: 600;
+					margin-bottom: 0.5rem;
+				}
+				.result-snippet {
+					font-size: 0.875rem;
+					color: var(--text-secondary);
+				}
+				.no-results {
+					text-align: center;
+					padding: 2rem;
+					color: var(--text-secondary);
+				}
+				mark {
+					background: var(--accent);
+					color: white;
+					padding: 0 0.2rem;
+					border-radius: 2px;
+				}
 			</style>
 		</head>
 		<body>
 			<button class="mobile-menu-button" onclick="toggleSidebar()">
-				☰
+
+			<!-- Search Results Overlay -->
+			<div id="search-results"></div>
+
 			</button>
 			
 			<!-- Sidebar -->
@@ -559,20 +748,109 @@ templ DocsLayoutWithExplorer(nav Navigation, doc Document, user User, explorer A
 					hljs.highlightAll();
 				});
 
-				// Search functionality
+				// Search state
-				async function searchDocs(query) {
+				let idx;
-					if (query.length < 2) return;
+				let searchResults = [];
 
-					try {
+				// Load index on page load
-						const response = await fetch('/docs/api/search?q=' + encodeURIComponent(query));
+				fetch('/docs/search-index.json')
-						const data = await response.json();
+					.then(r => r.json())
+					.then(data => {
+						// Initialize Lunr with fuzzy matching
+						idx = lunr(function() {
+							this.use(lunr.flex)
+							this.ref('id')
+							this.field('title', {boost: 10})
+							this.field('content', {boost: 1})
+							data.forEach(doc => this.add(doc))
+						})
+						console.log('Search index loaded:', data.length, 'documents')
+					})
+					.catch(err => console.error('Failed to load search index:', err));
 
-						// Display search results (you can enhance this)
+				// Search input with debounce
-						console.log('Search results:', data.results);
+				const searchInput = document.getElementById('docs-search');
-					} catch (error) {
+				const searchResultsDiv = document.getElementById('search-results');
-						console.error('Search failed:', error);
+
+				let debounceTimer;
+
+				searchInput.addEventListener('input', (e) => {
+					clearTimeout(debounceTimer);
+					debounceTimer = setTimeout(() => {
+						const query = e.target.value.trim();
+
+						if (query.length < 2) {
+							searchResultsDiv.style.display = 'none';
+							return;
+						}
+
+						// Search with fuzzy matching
+						const results = idx.search(query, {
+							fields: {title: {boost: 10}, content: 1},
+							expand: true
+						});
+
+						// Store results for highlighting
+						searchResults = results;
+
+						// Render results
+						renderSearchResults(results, query);
+					}, 150);
+				});
+
+				// Render search results
+				function renderSearchResults(results, query) {
+					if (results.length === 0) {
+						searchResultsDiv.innerHTML = '<div class="no-results">No results found</div>';
+						searchResultsDiv.style.display = 'block';
+						return;
 					}
+
+					searchResultsDiv.innerHTML = results.map(r => {
+						const doc = getDocById(r.ref);
+						if (!doc) return '';
+
+						const snippet = getSnippet(doc.content, query);
+
+						return `
+							<a href="${doc.url}" class="search-result">
+								<div class="result-title">${doc.title}</div>
+								<div class="result-snippet">${snippet}...</div>
+							</a>
+						`;
+					}).join('');
+
+					searchResultsDiv.style.display = 'block';
 				}
+
+				function getDocById(id) {
+					// This would be populated from the index
+					// For now, return a placeholder
+					return {title: id, url: '/docs/' + id.replace('.md', ''), content: ''};
+				}
+
+				function getSnippet(content, query) {
+					// Simple snippet extraction
+					const words = query.toLowerCase().split(/\s+/);
+					const contentLower = content.toLowerCase();
+
+					for (const word of words) {
+						const idx = contentLower.indexOf(word);
+						if (idx !== -1) {
+							const start = Math.max(0, idx - 50);
+							const end = Math.min(content.length, idx + 100);
+							return '...' + content.substring(start, end) + '...';
+						}
+					}
+					return content.substring(0, 150) + '...';
+				}
+
+				// Close search results when clicking outside
+				document.addEventListener('click', (e) => {
+					if (!searchResultsDiv.contains(e.target) && e.target !== searchInput) {
+						searchResultsDiv.style.display = 'none';
+					}
+				});
 			</script>
 		</body>
 	</html>