@nera-static/plugin-search 1.0.2 → 1.1.0

package/CHANGELOG.md

@@ -5,6 +5,54 @@ 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.1.0] - 2026-07-20
+
+### Added
+
+-   `--force` flag on the `nera-search` publish command, to deliberately
+    overwrite already-published templates and `assets/js/search.js`
+-   `assets/js/search.js` is now skipped when it already exists, instead of
+    being overwritten silently. Re-running the publish command no longer
+    discards local edits to the search script
+
+### Fixed
+
+-   **`getAppData` is now synchronous.** Nera only began awaiting plugin hooks
+    in generator 4.3.0, and that fix does not reach already-cloned sites. On
+    any earlier generator the previous `async` signature replaced the entire
+    `app` object with a Promise, silently discarding every `app.yaml` value —
+    `lang`, `translations`, `folders` — for this plugin and every plugin
+    ordered after it. Builds still exited 0, so the damage was invisible:
+    pages rendered with untranslated raw keys and no `lang` attribute
+-   the search index path no longer throws `Path must be a string` when
+    `app.yaml` defines a `folders` block without an `assets` key. It now falls
+    back to `./assets`, the generator's own default for that key
+
+### Changed
+
+-   configuration is read inside `getAppData` rather than at module load, so
+    edits to `config/search.yaml` take effect without a restart
+-   `@nera-static/plugin-utils` range raised to `^1.2.0`, which is where the
+    `force` option lands. The previous `^1.1.0` permitted but did not
+    guarantee it, so `--force` could be accepted and then silently ignored
+
+### Documentation
+
+-   corrected three false README claims: the search script is **not**
+    auto-included (the publish command copies it), the index path is **not**
+    fixed at `assets/search-index.json` (it follows `folders.assets` and
+    `output_filename`), and `app.searchIndexPath` is available to your own
+    templates but is not used by the shipped `search.pug`
+-   documented that the index is written into the **source** assets folder,
+    with a `.gitignore` note. Writing to `public/` is not possible — Nera
+    deletes and repopulates it after plugins run
+-   fixed an invalid `npx` invocation; the command is `npx nera-search`
+
+## [1.0.3] - 2025-07-25
+
+### Change
+- Enhance search.js to show parts of the results text
+
 ## [1.0.2] - 2025-07-25
 
 ### Fix

package/README.md

@@ -8,7 +8,7 @@ A plugin for the [Nera](https://github.com/seebaermichi/nera) static site genera
 - 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
+- Ships a client-side search script, published on request
 - Includes ready-to-use Pug template with BEM-compatible markup
 - Supports multiple search inputs per page
 - Full compatibility with Nera v4.2.0+
@@ -72,7 +72,10 @@ layout: pages/default.pug
 script(src="/js/search.js")
 ```
 
-The plugin will create `assets/js/search.js` and inject the `search-index.json` into your `/public` output.
+The plugin writes the index into your **source** assets folder, and Nera copies
+that folder into `public/` at the end of the render — so the built site serves
+it from `/search-index.json`. See [Generated Output](#-generated-output) for
+what this means for version control.
 
 You can include multiple search inputs on a page by using different `[data-results]` selectors.
 
@@ -90,7 +93,7 @@ You can include multiple search inputs on a page by using different `[data-resul
 To customize the default view:
 
 ```bash
-npx @nera-static/plugin-search run publish-template
+npx nera-search
 ```
 
 This will copy:
@@ -101,7 +104,15 @@ 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.
+The command also copies the `search.js` file to `assets/js/`. It handles DOM bindings and result generation.
+
+Both steps **skip if the destination already exists**, so re-running the command
+never discards your edits. To deliberately overwrite them with the packaged
+versions:
+
+```bash
+npx nera-search --force
+```
 
 ## 🎨 Styling
 
@@ -118,9 +129,32 @@ 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
+- `<assets folder>/<output_filename>`: contains all indexed page data. The
+  location follows `folders.assets` in your `config/app.yaml` (default
+  `./assets`) and `output_filename` in `config/search.yaml` (default
+  `search-index.json`) — it is **not** fixed at `assets/search-index.json`.
+- `assets/js/search.js`: minimal client-side logic for filtering and rendering,
+  copied by the publish command rather than by the render.
+- `app.searchIndexPath`: the index's public URL, added to `app` data. Available
+  to your own templates; the shipped `search.pug` does not use it, since
+  `search.js` resolves the path itself.
+
+### ⚠️ The index is written into your source tree
+
+The index has to be written into the **source** assets folder, not into
+`public/`. Nera deletes `public/` and then copies assets into it *after*
+plugins run, so anything a plugin writes directly to `public/` is discarded.
+
+That means each render creates or updates a generated file inside a directory
+you probably track in git. To keep it out of version control while still
+serving it, add it to `.gitignore`:
+
+```
+assets/search-index.json
+```
+
+Do **not** add it to `.neraignore` — that would stop Nera copying it into
+`public/`, and the search would find no index at runtime.
 
 ## 🧪 Development
 
@@ -134,8 +168,9 @@ 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
+- That `getAppData` stays synchronous and preserves existing `app` values
+- Fallback to `./assets` when `folders.assets` is absent
+- Config-driven field control, custom output filename, and HTML stripping
 
 ## 🧑‍💻 Author
 

package/bin/publish-template.js

@@ -1,37 +1,46 @@
 #!/usr/bin/env node
 
 import path from 'path'
-import fs from 'fs/promises'
+import fs from 'fs'
 import { fileURLToPath } from 'url'
 import { publishAllTemplates } from '@nera-static/plugin-utils'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const pluginName = 'plugin-search'
 const sourceDir = path.resolve(__dirname, '../views/')
+const force = process.argv.includes('--force')
 
 // Publish all pug templates to views/vendor/plugin-search/
 const result = publishAllTemplates({
     pluginName,
     sourceDir,
-    expectedPackageName: 'dummy', // for test-only override
+    force,
 })
 
-// Also publish search.js into assets/js/
-const publishSearchJS = async () => {
-    try {
-        const jsSource = path.join(sourceDir, 'search.js')
-        const jsTarget = path.resolve(process.cwd(), 'assets/js/search.js')
+// Also publish search.js into assets/js/. Same skip-if-exists rule as the
+// templates above — re-running this command must not discard user edits.
+const publishSearchJS = () => {
+    const jsSource = path.join(sourceDir, 'search.js')
+    const jsTarget = path.resolve(process.cwd(), 'assets/js/search.js')
 
-        await fs.mkdir(path.dirname(jsTarget), { recursive: true })
-        await fs.copyFile(jsSource, jsTarget)
+    if (fs.existsSync(jsTarget) && !force) {
+        console.log(
+            '⚠️  assets/js/search.js already exists — skipping.\n' +
+            '    Re-run with --force to overwrite (this will discard your edits).'
+        )
+        return true
+    }
+
+    try {
+        fs.mkdirSync(path.dirname(jsTarget), { recursive: true })
+        fs.copyFileSync(jsSource, jsTarget)
 
         console.log('✓ search.js copied to assets/js/search.js')
+        return true
     } catch (err) {
         console.error('✗ Failed to copy search.js to assets/js/', err)
-        process.exit(1)
+        return false
     }
 }
 
-publishSearchJS().then(() => {
-    process.exit(result ? 0 : 1)
-})
+process.exit(result && publishSearchJS() ? 0 : 1)

package/index.js

@@ -1,17 +1,22 @@
 import path from 'path'
-import fs from 'fs/promises'
+import fs from 'fs'
 import { getConfig } from '@nera-static/plugin-utils'
 
-const CONFIG_PATH = path.resolve(process.cwd(), 'config/search.yaml')
+const DEFAULT_ASSETS_FOLDER = './assets'
 
 function stripHtml(html) {
     return html.replace(/<[^>]*>/g, '').replace(/\s+/g, ' ').trim()
 }
 
-export async function getAppData({ app, pagesData }) {
-    const config = getConfig(CONFIG_PATH)
+// Must stay synchronous. The generator only started awaiting plugin hooks in
+// 4.3.0, and that fix never reaches already-cloned sites — an async hook there
+// replaces `app` with a Promise, silently wiping every `app.*` value for each
+// plugin that runs later.
+export function getAppData({ app, pagesData }) {
+    const config = getConfig(path.resolve(process.cwd(), 'config/search.yaml'))
     const filename = config.output_filename || 'search-index.json'
-    const outputPath = path.join(app.folders.assets, filename)
+    const assetsFolder = app?.folders?.assets || DEFAULT_ASSETS_FOLDER
+    const outputPath = path.join(assetsFolder, filename)
 
     const fields = config.fields || ['title', 'excerpt', 'content', 'href']
     const strip = config.strip_html ?? true
@@ -30,8 +35,8 @@ export async function getAppData({ app, pagesData }) {
         return item
     })
 
-    await fs.mkdir(path.dirname(outputPath), { recursive: true })
-    await fs.writeFile(outputPath, JSON.stringify(index, null, 2), 'utf-8')
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true })
+    fs.writeFileSync(outputPath, JSON.stringify(index, null, 2), 'utf-8')
 
     return {
         ...app,

package/package.json

@@ -1,57 +1,58 @@
 {
-  "name": "@nera-static/plugin-search",
-  "version": "1.0.2",
-  "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"
-  }
+    "name": "@nera-static/plugin-search",
+    "version": "1.1.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.2.0"
+    },
+    "engines": {
+        "node": ">=18"
+    },
+    "devDependencies": {
+        "eslint": "^9.31.0",
+        "husky": "^9.1.7",
+        "pug": "^3.0.3",
+        "vitest": "^3.2.4"
+    },
+    "sideEffects": false
 }

package/views/search.js

@@ -12,21 +12,46 @@ document.addEventListener('DOMContentLoaded', () => {
                 input.addEventListener('input', () => {
                     const query = input.value.toLowerCase()
 
+                    if (!query) {
+                        resultList.innerHTML = ''
+                        return
+                    }
+
                     const results = data.filter((item) => {
-                        return Object.values(item).some(val =>
-                            typeof val === 'string' && val.toLowerCase().includes(query)
-                        )
+                        return Object.values(item).some(val => {
+                            if (typeof val === 'string') {
+                                const lowerVal = val.toLowerCase()
+                                const matchIndex = lowerVal.indexOf(query)
+                                if (matchIndex !== -1) {
+                                    const words = val.split(/\s+/)
+                                    const matchWordIndex = words.findIndex(word => word.toLowerCase().includes(query))
+
+                                    const snippetStart = Math.max(0, matchWordIndex - 5)
+                                    const snippetEnd = Math.min(words.length, matchWordIndex + 6)
+                                    const snippet = words.slice(snippetStart, snippetEnd).join(' ')
+
+                                    const highlighted = snippet.replace(
+                                        new RegExp(`(${query})`, 'ig'),
+                                        '<span class="bg-yellow-100">$1</span>'
+                                    )
+                                    item.resultText = `...${highlighted}...`
+                                    return true
+                                }
+                            }
+
+                            return false
+                        })
                     })
 
                     resultList.innerHTML = results.map((item) => {
                         const title = item.title || item.href || 'Untitled'
-                        const desc = item.excerpt || item.description || ''
+                        const desc = item.excerpt || item.description || item.resultText
                         return `
-                <li class="search__item">
-                    <a class="search__link" href="${item.href}">${title}</a>
-                    ${desc ? `<p class="search__description">${desc}</p>` : ''}
-                </li>
-            `
+                            <li class="list-none">
+                                <a class="" href="${item.href}">${title}</a>
+                                ${desc ? `<p class="">${desc}</p>` : ''}
+                            </li>
+                    `
                     }).join('')
                 })
             })