@docmd/plugin-search 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 docmd (docmd.io)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @docmd/plugin-search
+
+Adds offline, full-text search to **docmd** sites.
+
+- **Zero Config:** Enabled by default.
+- **Offline:** Generates a `search-index.json` at build time.
+- **Fast:** Uses `minisearch` for fuzzy matching.

package/assets/docmd-search.js

@@ -0,0 +1,229 @@
+// Source file from the docmd project — https://github.com/docmd-io/docmd
+
+/* 
+ * Client-side search functionality for docmd
+ */
+
+(function() {
+    let miniSearch = null;
+    let isIndexLoaded = false;
+    let selectedIndex = -1; // Track keyboard selection
+    
+    const searchModal = document.getElementById('docmd-search-modal');
+    const searchInput = document.getElementById('docmd-search-input');
+    const searchResults = document.getElementById('docmd-search-results');
+
+    const rawRoot = window.DOCMD_ROOT || './';
+    const ROOT_PATH = rawRoot.endsWith('/') ? rawRoot : rawRoot + '/';
+
+    if (!searchModal) return;
+
+    const emptyStateHtml = '<div class="search-initial">Type to start searching...</div>';
+
+    // 1. Open/Close Logic
+    function openSearch() {
+        searchModal.style.display = 'flex';
+        searchInput.focus();
+        
+        if (!searchInput.value.trim()) {
+            searchResults.innerHTML = emptyStateHtml;
+            selectedIndex = -1;
+        }
+        
+        if (!isIndexLoaded) loadIndex();
+    }
+
+    function closeSearch() {
+        searchModal.style.display = 'none';
+        selectedIndex = -1; // Reset selection
+    }
+
+    // 2. Keyboard Navigation & Shortcuts
+    document.addEventListener('keydown', (e) => {
+        // Open: Cmd+K / Ctrl+K
+        if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
+            e.preventDefault();
+            if (searchModal.style.display === 'flex') {
+                closeSearch();
+            } else {
+                openSearch();
+            }
+        }
+        
+        // Context: Only handle these if search is open
+        if (searchModal.style.display === 'flex') {
+            const items = searchResults.querySelectorAll('.search-result-item');
+            
+            if (e.key === 'Escape') {
+                e.preventDefault();
+                closeSearch();
+            }
+            else if (e.key === 'ArrowDown') {
+                e.preventDefault();
+                if (items.length === 0) return;
+                selectedIndex = (selectedIndex + 1) % items.length;
+                updateSelection(items);
+            }
+            else if (e.key === 'ArrowUp') {
+                e.preventDefault();
+                if (items.length === 0) return;
+                selectedIndex = (selectedIndex - 1 + items.length) % items.length;
+                updateSelection(items);
+            }
+            else if (e.key === 'Enter') {
+                e.preventDefault();
+                if (selectedIndex >= 0 && items[selectedIndex]) {
+                    items[selectedIndex].click();
+                } else if (items.length > 0) {
+                    // If nothing selected but results exist, click the first one on Enter
+                    items[0].click();
+                }
+            }
+        }
+    });
+
+    function updateSelection(items) {
+        items.forEach((item, index) => {
+            if (index === selectedIndex) {
+                item.classList.add('selected');
+                item.scrollIntoView({ block: 'nearest' });
+            } else {
+                item.classList.remove('selected');
+            }
+        });
+    }
+
+    // Click handlers
+    document.querySelectorAll('.docmd-search-trigger').forEach(btn => {
+        btn.addEventListener('click', openSearch);
+    });
+
+    searchModal.addEventListener('click', (e) => {
+        if (e.target === searchModal) closeSearch();
+    });
+
+    // 3. Index Loading Logic
+    async function loadIndex() {
+        try {
+
+            const indexUrl = `${ROOT_PATH}search-index.json`;
+
+            console.log('Fetching index from:', indexUrl); // Debug log
+            
+            const response = await fetch(indexUrl);
+            
+            // Check content type to prevent "Unexpected token <" error
+            const contentType = response.headers.get("content-type");
+            if (contentType && contentType.includes("text/html")) {
+                throw new Error("Server returned HTML instead of JSON. Check paths.");
+            }
+            
+            if (!response.ok) throw new Error(response.status);
+
+            const jsonString = await response.text();
+            
+            miniSearch = MiniSearch.loadJSON(jsonString, {
+                fields: ['title', 'headings', 'text'],
+                storeFields: ['title', 'id', 'text'],
+                searchOptions: {
+                    fuzzy: 0.2,
+                    prefix: true,
+                    boost: { title: 2, headings: 1.5 }
+                }
+            });
+            
+            isIndexLoaded = true;
+            // console.log('Search index loaded');
+            
+            if (searchInput.value.trim()) {
+                searchInput.dispatchEvent(new Event('input'));
+            }
+
+        } catch (e) {
+            console.error('Failed to load search index', e);
+            searchResults.innerHTML = '<div class="search-error">Failed to load search index.</div>';
+        }
+    }
+
+    // Helper: Snippets (Same as before)
+    function getSnippet(text, query) {
+        if (!text) return '';
+        const terms = query.split(/\s+/).filter(t => t.length > 2);
+        const lowerText = text.toLowerCase();
+        let bestIndex = -1;
+        
+        for (const term of terms) {
+            const idx = lowerText.indexOf(term.toLowerCase());
+            if (idx >= 0) { bestIndex = idx; break; }
+        }
+        
+        const contextSize = 60;
+        let start = 0;
+        let end = 120;
+        
+        if (bestIndex >= 0) {
+            start = Math.max(0, bestIndex - contextSize);
+            end = Math.min(text.length, bestIndex + contextSize);
+        }
+        
+        let snippet = text.substring(start, end);
+        if (start > 0) snippet = '...' + snippet;
+        if (end < text.length) snippet = snippet + '...';
+        
+        const safeTerms = terms.map(t => t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
+        if (safeTerms) {
+            const highlightRegex = new RegExp(`(${safeTerms})`, 'gi');
+            snippet = snippet.replace(highlightRegex, '<mark>$1</mark>');
+        }
+        return snippet;
+    }
+
+    // 4. Search Execution
+    searchInput.addEventListener('input', (e) => {
+        const query = e.target.value.trim();
+        selectedIndex = -1; // Reset selection on new input
+        
+        if (!query) {
+            searchResults.innerHTML = emptyStateHtml;
+            return;
+        }
+        
+        if (!isIndexLoaded) return;
+
+        const results = miniSearch.search(query);
+        renderResults(results, query);
+    });
+
+    function renderResults(results, query) {
+        if (results.length === 0) {
+            searchResults.innerHTML = '<div class="search-no-results">No results found.</div>';
+            return;
+        }
+
+        const html = results.slice(0, 10).map((result, index) => {
+            const snippet = getSnippet(result.text, query);
+
+            const linkHref = `${ROOT_PATH}${result.id}`;
+
+            // Add data-index for mouse interaction tracking if needed
+            return `
+                <a href="${linkHref}" class="search-result-item" data-index="${index}" onclick="window.closeDocmdSearch()">
+                    <div class="search-result-title">${result.title}</div>
+                    <div class="search-result-preview">${snippet}</div>
+                </a>
+            `;
+        }).join('');
+
+        searchResults.innerHTML = html;
+        
+        // Optional: Allow mouse hover to update selectedIndex
+        searchResults.querySelectorAll('.search-result-item').forEach((item, idx) => {
+            item.addEventListener('mouseenter', () => {
+                selectedIndex = idx;
+                updateSelection(searchResults.querySelectorAll('.search-result-item'));
+            });
+        });
+    }
+    
+    window.closeDocmdSearch = closeSearch;
+})();

package/index.js

@@ -0,0 +1,67 @@
+const path = require('path');
+const fs = require('fs/promises');
+const MiniSearch = require('minisearch');
+
+/**
+ * Hook to run after HTML generation is complete.
+ * @param {Object} context - { config, pages, outputDir, log }
+ */
+async function onPostBuild({ config, pages, outputDir, log }) {
+  if (config.search === false) return;
+  
+  if(log) log('🔍 Generating search index...');
+
+  const searchData = [];
+
+  // Extract search data from processed pages
+  pages.forEach(page => {
+    // We expect 'page.searchData' to be populated by the Core processor
+    if (page.searchData) {
+      // Normalize ID to be the URL path
+      let pageId = page.outputPath.replace(/\\/g, '/');
+      if (pageId.endsWith('/index.html')) pageId = pageId.slice(0, -10);
+      if (pageId.endsWith('.html')) pageId = pageId.slice(0, -5);
+      
+      searchData.push({
+        id: pageId,
+        title: page.searchData.title,
+        text: page.searchData.content,
+        headings: (page.searchData.headings || []).join(' ')
+      });
+    }
+  });
+
+  const miniSearch = new MiniSearch({
+    fields: ['title', 'headings', 'text'],
+    storeFields: ['title', 'id', 'text'],
+    searchOptions: { boost: { title: 2, headings: 1.5 }, fuzzy: 0.2 }
+  });
+
+  miniSearch.addAll(searchData);
+
+  const json = JSON.stringify(miniSearch.toJSON());
+  await fs.writeFile(path.join(outputDir, 'search-index.json'), json);
+}
+
+/**
+ * Returns path to client-side assets to be copied.
+ */
+function getAssets() {
+  return [
+    // 1. External Library (CDN)
+    {
+      url: 'https://cdn.jsdelivr.net/npm/minisearch@7.2.0/dist/umd/index.min.js',
+      type: 'js',
+      location: 'body' // Load at end of body
+    },
+    // 2. Local Logic (The glue code)
+    {
+      src: path.join(__dirname, 'assets/docmd-search.js'),
+      dest: 'assets/js/docmd-search.js', // Renamed for clarity
+      type: 'js',
+      location: 'body'
+    }
+  ];
+}
+
+module.exports = { onPostBuild, getAssets };

package/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@docmd/plugin-search",
+  "version": "0.4.0",
+  "description": "Offline full-text search for docmd",
+  "main": "index.js",
+  "dependencies": {
+    "minisearch": "^7.2.0"
+  },
+  "license": "MIT"
+}