@nera-static/plugin-search 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-07-25
+
+### Added
+
+- Initial release of `@nera-static/plugin-search`
+- Generates a `search-index.json` file from page metadata and content
+- Supports configurable fields via `config/search.yaml`
+- Option to strip HTML tags from content before indexing
+- Auto-injects `search.js` script to `assets/js/search.js`
+- Simple search interface and results rendering via `views/search.pug`
+- Allows multiple search inputs per page via `[data-search-input]` selectors
+- Provides `publish-template` command to copy `search.pug` for customization
+- Comprehensive test suite to validate index generation and file handling
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michael Becker
+
+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,159 @@
+# @nera-static/plugin-search
+
+A plugin for the [Nera](https://github.com/seebaermichi/nera) static site generator that adds a lightweight client-side search functionality. It builds a searchable JSON index from your content and provides a ready-to-use search interface – all without requiring a backend.
+
+## ✨ Features
+
+- Creates a `search-index.json` from page content and metadata
+- Fully client-side – no backend or JavaScript framework needed
+- Configurable search fields (e.g., `title`, `excerpt`, `description`)
+- Option to strip HTML from content before indexing
+- Auto-includes search script in assets
+- Includes ready-to-use Pug template with BEM-compatible markup
+- Supports multiple search inputs per page
+- Full compatibility with Nera v4.2.0+
+
+## 🚀 Installation
+
+Install the plugin in your Nera project:
+
+```bash
+npm install @nera-static/plugin-search
+```
+
+The plugin is automatically detected and run during the render process.
+
+## ⚙️ Configuration
+
+Configure the plugin via `config/search.yaml` (optional):
+
+```yaml
+output_filename: search-index.json
+
+fields:
+  - title
+  - excerpt
+  - content
+  - description
+  - href
+
+strip_html: true
+```
+
+### Field Notes
+
+- `fields`: List of metadata fields to include in the index.
+- `content`: Always pulled from the markdown content itself.
+- `strip_html`: If `true`, HTML is removed from content before indexing.
+
+## 🧩 Usage
+
+### Add Search Page
+
+```yaml
+---
+title: Search
+layout: pages/default.pug
+---
+```
+
+```pug
+.section.search
+  h1.search__title Search
+
+  input.search__input(
+    type="search",
+    placeholder="Search...",
+    data-search-input,
+    data-results="[data-search__results]"
+  )
+
+  ul.search__results(data-search__results)
+script(src="/js/search.js")
+```
+
+The plugin will create `assets/js/search.js` and inject the `search-index.json` into your `/public` output.
+
+You can include multiple search inputs on a page by using different `[data-results]` selectors.
+
+### Example Search Result Output
+
+```html
+<li class="search__item">
+    <a class="search__link" href="${item.href}">${title}</a>
+    ${desc ? `<p class="search__description">${desc}</p>` : ''}
+</li>
+```
+
+## 🛠️ Template Publishing
+
+To customize the default view:
+
+```bash
+npx @nera-static/plugin-search run publish-template
+```
+
+This will copy:
+
+```
+views/vendor/plugin-search/search.pug
+```
+
+to your local project. You can now edit or extend the search markup freely.
+
+The plugin also automatically copies `assets/search-content.json` to `assets/js/search.js` on render. This file handles DOM bindings and result generation.
+
+## 🎨 Styling
+
+Default template uses semantic HTML and includes minimal structure. Recommended BEM class names:
+
+- `.search`
+- `.search__input`
+- `.search__results`
+- `.search__item`
+- `.search__title`
+- `.search__description`
+
+Customize freely via your own stylesheets.
+
+## 📊 Generated Output
+
+- `assets/search-index.json`: contains all indexed page data
+- `assets/js/search.js`: minimal client-side logic for filtering and rendering
+- `app.searchIndexPath`: injected into `app` data for template access
+
+## 🧪 Development
+
+```bash
+npm install
+npm test
+npm run lint
+```
+
+Tests use [Vitest](https://vitest.dev) and cover:
+
+- Index creation from `pagesData`
+- Correct JSON structure and file writing
+- `search.js` copy to assets folder
+- Config-driven field control and HTML stripping
+
+## 🧑‍💻 Author
+
+Michael Becker
+[https://github.com/seebaermichi](https://github.com/seebaermichi)
+
+## 🔗 Links
+
+- [Plugin Repository](https://github.com/seebaermichi/nera-plugin-search)
+- [NPM Package](https://www.npmjs.com/package/@nera-static/plugin-search)
+- [Nera Static Site Generator](https://github.com/seebaermichi/nera)
+
+## 🧩 Compatibility
+
+- **Nera**: v4.2.0+
+- **Node.js**: >= 18
+- **Plugin API**: Uses `getAppData()` for index creation and asset copying
+
+## 📦 License
+
+MIT

package/config/search.yaml

@@ -0,0 +1,7 @@
+fields:
+  - title
+  - excerpt
+  - content
+  - href
+strip_html: true
+output_filename: search-index.json

package/index.js

@@ -0,0 +1,46 @@
+import path from 'path'
+import fs from 'fs/promises'
+import { getConfig } from '@nera-static/plugin-utils'
+import { fileURLToPath } from 'url'
+
+const CONFIG_PATH = path.resolve(process.cwd(), 'config/search.yaml')
+
+function stripHtml(html) {
+    return html.replace(/<[^>]*>/g, '').replace(/\s+/g, ' ').trim()
+}
+
+export async function getAppData({ app, pagesData }) {
+    const config = getConfig(CONFIG_PATH)
+    const filename = config.output_filename || 'search-index.json'
+    const outputPath = path.join(app.folders.assets, filename)
+
+    const fields = config.fields || ['title', 'excerpt', 'content', 'href']
+    const strip = config.strip_html ?? true
+
+    const index = pagesData.map(({ meta, content }) => {
+        const item = {}
+
+        for (const field of fields) {
+            if (field === 'content') {
+                item.content = strip ? stripHtml(content) : content
+            } else if (meta[field]) {
+                item[field] = meta[field]
+            }
+        }
+
+        return item
+    })
+
+    fs.writeFile(outputPath, JSON.stringify(index, null, 2), 'utf-8')
+
+    const __dirname = path.dirname(fileURLToPath(import.meta.url))
+    const sourceJS = path.join(__dirname, 'views', 'search.js')
+    const targetJS = path.join(app.folders.assets, 'js', 'search.js')
+    await fs.mkdir(path.dirname(targetJS), { recursive: true })
+    await fs.copyFile(sourceJS, targetJS)
+
+    return {
+        ...app,
+        searchIndexPath: `/${filename}`
+    }
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@nera-static/plugin-search",
+  "version": "1.0.0",
+  "description": "A plugin for the Nera static site generator that builds a JSON search index and provides a client-side search script.",
+  "main": "index.js",
+  "scripts": {
+    "publish-template": "node ./bin/publish-template.js",
+    "lint": "eslint .",
+    "test": "vitest"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./index.js"
+  },
+  "bin": {
+    "nera-search": "./bin/publish-template.js"
+  },
+  "files": [
+    "bin",
+    "config",
+    "views",
+    "index.js",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "nera",
+    "plugin",
+    "search",
+    "static-site",
+    "client-side-search",
+    "search-index",
+    "lunr",
+    "json"
+  ],
+  "author": "Michael Becker",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/seebaermichi/nera-plugin-search.git"
+  },
+  "bugs": {
+    "url": "https://github.com/seebaermichi/nera-plugin-search/issues"
+  },
+  "homepage": "https://github.com/seebaermichi/nera-plugin-search#readme",
+  "dependencies": {
+    "@nera-static/plugin-utils": "^1.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "eslint": "^9.31.0",
+    "husky": "^9.1.7",
+    "pug": "^3.0.3",
+    "vitest": "^3.2.4"
+  }
+}

package/views/search.js

@@ -0,0 +1,34 @@
+document.addEventListener('DOMContentLoaded', () => {
+    const inputs = document.querySelectorAll('[data-search-input]')
+
+    fetch('/search-index.json')
+        .then((res) => res.json())
+        .then((data) => {
+            inputs.forEach((input) => {
+                const resultSelector = input.getAttribute('data-results')
+                const resultList = document.querySelector(resultSelector)
+                if (!resultList) return
+
+                input.addEventListener('input', () => {
+                    const query = input.value.toLowerCase()
+
+                    const results = data.filter((item) => {
+                        return Object.values(item).some(val =>
+                            typeof val === 'string' && val.toLowerCase().includes(query)
+                        )
+                    })
+
+                    resultList.innerHTML = results.map((item) => {
+                        const title = item.title || item.href || 'Untitled'
+                        const desc = item.excerpt || item.description || ''
+                        return `
+                <li class="search__item">
+                    <a class="search__link" href="${item.href}">${title}</a>
+                    ${desc ? `<p class="search__description">${desc}</p>` : ''}
+                </li>
+            `
+                    }).join('')
+                })
+            })
+        })
+})

package/views/search.pug

@@ -0,0 +1,13 @@
+.section.search
+  h1.search__title Search
+
+  input.search__input(
+    type="search",
+    placeholder="Search...",
+    data-search-input,
+    data-results="[data-search__results]"
+  )
+
+  ul.search__results(data-search__results)
+
+script(src="/js/search.js")