@nera-static/plugin-navigation 2.0.1 → 2.2.0

package/CHANGELOG.md

@@ -0,0 +1,91 @@
+# 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).
+
+## [2.2.0] - 2026-07-19
+
+### Fixed
+
+-   the `publish-template` command is now actually shipped. `bin/` was absent
+    from the published package and no `bin` entry existed, so the command
+    documented in the README could never resolve
+-   published templates now include their `partials/` and `helper/` files, so
+    they compile. Previously only the three top-level templates were copied and
+    every one of them failed on its first `include` (requires
+    `@nera-static/plugin-utils` ^1.2.0)
+-   a `navigation.yaml` entry missing `href` no longer crashes the build with a
+    `TypeError` from inside `node_modules`; the entry is skipped with a warning
+    naming its position
+
+### Added
+
+-   a commented default `config/navigation.yaml` is now shipped
+-   `npx nera-navigation --force` re-publishes over existing templates,
+    discarding local edits
+
+### Changed
+
+-   `@nera-static/plugin-utils` range widened to `^1.2.0`
+-   navigation config is resolved per call rather than at module load
+
+## [2.1.0] - 2024-12-27
+
+### Added
+
+-   Professional CHANGELOG.md for release tracking
+-   Enhanced README.md with comprehensive documentation
+-   Support for Nera v4.1.0 static site generator
+-   Template publishing system via `bin/publish-template.js`
+-   BEM (Block Element Modifier) CSS methodology for all templates
+-   Comprehensive test suite with 14 tests covering all functionality
+
+### Changed
+
+-   Updated development dependencies for security and performance
+-   Improved package.json metadata and repository references
+-   Enhanced code documentation and examples
+-   Modernized CSS classes using BEM methodology:
+    -   `.nav`, `.nav__list`, `.nav__item`, `.nav__link`
+    -   `.nav__link--active`, `.nav__link--active-path`
+    -   `.nav--list`, `.nav__list--pipe-separated`
+
+### Technical Details
+
+-   Maintains stable API with `getAppData()` function
+-   Full compatibility with Nera's plugin system
+-   Zero breaking changes from previous version
+-   All tests passing (14/14)
+-   Template publishing to `views/vendor/plugin-navigation/`
+
+## [2.0.1] - Previous Release
+
+### Note
+
+-   This version was already published on npm before our enhancements
+
+## [2.0.0] - 2024-07-19
+
+### Added
+
+-   Initial stable release for Nera static site generator
+-   Navigation generation from YAML configuration
+-   Support for multi-level navigations (main, footer, etc.)
+-   Built-in Pug templates and mixins
+-   Automatic active/path highlighting
+-   Comprehensive test coverage
+
+### Features
+
+-   Single and multi-navigation support
+-   Flexible CSS class configuration
+-   Template inheritance and mixins
+-   Integration with @nera-static/plugin-utils
+
+### Dependencies
+
+-   Node.js >=18 support
+-   ES modules architecture
+-   Modern development tooling

package/README.md

@@ -1,57 +1,67 @@
 # @nera-static/plugin-navigation
 
-A plugin for the [Nera](https://github.com/seebaermichi/nera) static site generator to create navigations from config files. Supports mixins and templates for easy rendering.
+A plugin for the [Nera](https://github.com/seebaermichi/nera) static site generator to create navigations from config files. Supports mixins and templates for easy rendering and styling.
 
 ## ✨ Features
 
--   Define one or more navigations via YAML config
--   Access navigation data in your templates (`app.nav`)
--   Support for multi-level navigations (e.g. main, footer)
--   Includes built-in Pug templates and mixins for rendering:
-    -   Pipe-separated links
-    -   Link lists
-    -   Mixin-powered flexible layout
--   Automatic active/path highlighting support
--   Zero-runtime, static navigation structure
+- Define one or more navigations via YAML config
+- Access navigation data directly in templates (`app.nav`)
+- Support for multi-level navigations (e.g., main, footer)
+- Includes ready-to-use Pug templates and mixins
+- Automatic active and path highlighting
+- Static, zero-runtime overhead
+- Full compatibility with Nera v4.1.0+
 
 ## 🚀 Installation
 
-You can install this plugin by running the following in the root folder of your Nera project:
+Install the plugin in your Nera project:
 
 ```bash
 npm install @nera-static/plugin-navigation
 ```
 
-Then create a `navigation.yaml` file inside your project’s `config/` directory:
+Then create the configuration file in your project:
+
+```bash
+mkdir -p config
+touch config/navigation.yaml
+```
+
+This creates:
 
 ```
 config/
 └── navigation.yaml
 ```
 
-Nera will automatically detect the plugin and load your navigation configuration. No additional setup or imports are required.
+The plugin ships a commented default at
+`node_modules/@nera-static/plugin-navigation/config/navigation.yaml` — copy it
+as a starting point. It is read from **your** project only; the packaged copy
+is documentation, not a fallback.
+
+Nera will automatically detect the plugin and load the configuration.
 
 ## ⚙️ Configuration
 
-### Single Navigation
+Define your navigation(s) in `config/navigation.yaml`.
 
-Example `navigation/config/navigation.yaml`:
+### Single Navigation
 
 ```yaml
 elements:
-    - href: /index.html
-      name: Home
-    - href: /service/service.html
-      name: Service
-    - href: /prices.html
-      name: Prices
-    - href: /contact.html
-      name: Contact
-    - href: /about-us/index.html
-      name: About us
+  - href: /index.html
+    name: Home
+  - href: /service/service.html
+    name: Service
+  - href: /prices.html
+    name: Prices
+  - href: /contact.html
+    name: Contact
+  - href: /about-us/index.html
+    name: About us
 ```
 
-Access it in your templates via:
+Access in templates:
 
 ```pug
 app.nav.elements
@@ -61,67 +71,108 @@ app.nav.elements
 
 ```yaml
 elements:
-    main:
-        - href: /index.html
-          name: Home
-        - href: /service/service.html
-          name: Service
-    footer:
-        - href: /imprint.html
-          name: Imprint
+  main:
+    - href: /index.html
+      name: Home
+    - href: /service/service.html
+      name: Service
+  footer:
+    - href: /imprint.html
+      name: Imprint
 ```
 
-Use:
+Access in templates:
 
 ```pug
 app.nav.main.elements
 app.nav.footer.elements
 ```
 
-Each element has: `href`, `name`, `path`.
+Each element includes `href`, `name`, and `path`.
 
-## 🧩 Rendering Options
+## 🧩 Usage
 
-### Custom Rendering
+### Manual Rendering
 
-Use the `app.nav.*.elements` arrays in your templates manually or via your own loops.
+Loop through `app.nav.*.elements` directly in your Pug templates.
 
-### Built-in Templates
+## 🛠️ Template Publishing
 
-If you like to, include one of the built-in templates in `views/`:
+Use the default templates provided by the plugin:
 
-```pug
-include ../../src/plugins/navigation/views/simple-navigation
+```bash
+npx nera-navigation
 ```
 
-Other available templates:
+This copies every template file — including `partials/` and `helper/`, which
+the top-level templates include — to:
 
--   `pipe-separated-navigation.pug`
--   `link-list-navigation.pug`
+```
+views/vendor/plugin-navigation/
+```
 
-### Built-in Mixins
+Then include them in your layouts or pages as needed.
 
-If using multiple navigations, use the mixins in `views/mixins/`:
+Publishing **skips** if `views/vendor/plugin-navigation/` already exists, so
+your edits are never overwritten. To pull in updated templates after a plugin
+upgrade, discarding your changes to them:
 
-```pug
-include ../../src/plugins/navigation/views/mixins/pipe-separated-navigation
+```bash
+npx nera-navigation --force
+```
+
+## 🎨 Styling
+
+The plugin uses BEM CSS methodology:
 
-+pipeSeparatedNav(app.nav.main.elements, app.nav.main.className)
+```css
+.nav { }
+.nav__list { }
+.nav__item { }
+.nav__item--inline { }
+.nav__link { }
+.nav__separator { }
+.nav__link--active { }
+.nav__link--active-path { }
 ```
 
-> The optional `nav_class` value can be set in the YAML config.
+Override or extend these classes in your project’s CSS.
+
+## 📊 Generated Output
+
+The plugin injects navigation data into `app.nav` without generating HTML. Use templates or mixins for output.
 
 ## 🧪 Development
 
 ```bash
 npm install
-npm run test
+npm test
+npm run lint
 ```
 
+Tests use [Vitest](https://vitest.dev) and validate:
+
+- Navigation data structure
+- Multi-level navigation support
+- Template rendering
+- Class handling and active link detection
+
 ## 🧑‍💻 Author
 
 Michael Becker
-[GitHub](https://github.com/seebaermichi)
+[https://github.com/seebaermichi](https://github.com/seebaermichi)
+
+## 🔗 Links
+
+- [Plugin Repository](https://github.com/seebaermichi/nera-plugin-navigation)
+- [NPM Package](https://www.npmjs.com/package/@nera-static/plugin-navigation)
+- [Nera Static Site Generator](https://github.com/seebaermichi/nera)
+
+## 🧩 Compatibility
+
+- **Nera**: v4.1.0+
+- **Node.js**: >= 18
+- **Plugin API**: Uses `getAppData()` for injecting navigation structure
 
 ## 📦 License
 

package/bin/publish-template.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { publishAllTemplates } from '@nera-static/plugin-utils'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const pluginName = 'plugin-navigation'
+const sourceDir = path.resolve(__dirname, '../views/')
+const force = process.argv.includes('--force')
+
+const result = publishAllTemplates({
+    pluginName,
+    sourceDir,
+    force,
+})
+
+process.exit(result ? 0 : 1)

package/config/navigation.yaml

@@ -0,0 +1,30 @@
+# Default configuration for @nera-static/plugin-navigation.
+#
+# This file is documentation and a starting point. The plugin reads
+# config/navigation.yaml from YOUR project root, not from this package —
+# copy this file there and edit it.
+
+# CSS class applied to the link matching the current page.
+active_class: active
+
+# CSS class applied to a link whose path is an ancestor of the current page.
+active_path_class: active-path
+
+# Base CSS class for the navigation element.
+nav_class: nav
+
+# A single navigation: a flat list, available as app.nav.elements
+elements:
+    - href: /index.html
+      name: Home
+
+# For several navigations, nest them under names instead. Each becomes
+# app.nav.<name>.elements:
+#
+# elements:
+#   main:
+#     - href: /index.html
+#       name: Home
+#   footer:
+#     - href: /imprint.html
+#       name: Imprint

package/index.js

@@ -1,18 +1,43 @@
 import path from 'path'
 import { getConfig } from '@nera-static/plugin-utils'
 
-// Default location to look for navigation.yaml in host project
-const HOST_CONFIG_PATH = path.resolve(process.cwd(), 'config/navigation.yaml')
-
-function getNavElements(elements) {
-    return elements.map((element) => ({
-        ...element,
-        path: path.posix.dirname(element.href),
-    }))
+// Resolved per call rather than at module scope: the host project's cwd is
+// what matters, and resolving lazily is what makes this testable.
+function getHostConfigPath() {
+    return path.resolve(process.cwd(), 'config/navigation.yaml')
+}
+
+function getNavElements(elements, groupName) {
+    if (!Array.isArray(elements)) {
+        console.warn(
+            `⚠️ navigation.yaml: expected a list of elements${groupName ? ` under "${groupName}"` : ''}, got ${typeof elements}. Skipping.`
+        )
+        return []
+    }
+
+    return elements
+        .filter((element, index) => {
+            // A missing href is an ordinary YAML typo. Without this guard
+            // path.posix.dirname throws a TypeError from inside node_modules,
+            // which tells the user nothing about which entry is at fault.
+            if (!element || typeof element.href !== 'string') {
+                const where = groupName ? `${groupName}[${index}]` : `elements[${index}]`
+                console.warn(
+                    `⚠️ navigation.yaml: skipping ${where} — it has no "href".`
+                )
+                return false
+            }
+
+            return true
+        })
+        .map((element) => ({
+            ...element,
+            path: path.posix.dirname(element.href),
+        }))
 }
 
 function getMainNav() {
-    const navConfig = getConfig(HOST_CONFIG_PATH)
+    const navConfig = getConfig(getHostConfigPath())
 
     navConfig.activeClass = navConfig.active_class || 'active'
     navConfig.activePathClass = navConfig.active_path_class || 'active-path'
@@ -24,7 +49,7 @@ function getMainNav() {
         for (const key in navConfig.elements) {
             navConfig[key] = {
                 className: `${key}-${navConfig.navClass}`,
-                elements: getNavElements(navConfig.elements[key]),
+                elements: getNavElements(navConfig.elements[key], key),
             }
         }
     }

package/package.json

@@ -1,9 +1,10 @@
 {
     "name": "@nera-static/plugin-navigation",
-    "version": "2.0.1",
+    "version": "2.2.0",
     "description": "A plugin for Nera static site generator to generate navigations with optional templates and mixins.",
     "main": "index.js",
     "scripts": {
+        "publish-template": "node ./bin/publish-template.js",
         "lint": "eslint .",
         "test": "vitest"
     },
@@ -11,10 +12,15 @@
     "exports": {
         ".": "./index.js"
     },
+    "bin": {
+        "nera-navigation": "./bin/publish-template.js"
+    },
     "files": [
+        "bin",
         "config",
         "index.js",
-        "views"
+        "views",
+        "CHANGELOG.md"
     ],
     "keywords": [
         "nera",
@@ -35,14 +41,14 @@
     },
     "homepage": "https://github.com/seebaermichi/nera-plugin-navigation#readme",
     "dependencies": {
-        "@nera-static/plugin-utils": "^1.0.3"
+        "@nera-static/plugin-utils": "^1.2.0"
     },
     "engines": {
         "node": ">=18"
     },
     "devDependencies": {
         "cheerio": "^1.1.0",
-        "eslint": "^9.31.0",
+        "eslint": "^9.17.0",
         "husky": "^9.1.7",
         "pug": "^3.0.3",
         "vitest": "^3.2.4"

package/views/helper/mixins.pug

@@ -1,2 +1,2 @@
 mixin link(item, activeClass, activePathClass)
-  a(href=item.href, class=`${activeClass}${activePathClass}`) #{ item.name }
+  a.nav__link(href=item.href, class=`${activeClass} ${activePathClass}`.trim()) #{ item.name }

package/views/helper/setup.pug

@@ -1,6 +1,6 @@
 each item, index in elements || app.nav.elements
   - const isActive = item.href === meta.fullPath
-  - const activeClass = isActive ? app.nav.activeClass : ''
+  - const activeClass = isActive ? 'nav__link--active' : ''
   - const isNotHome = meta.dirname !== '/'
   - const isParent = isNotHome && item.href.indexOf(meta.dirname) === 0
-  - const activePathClass = !isActive && isParent ? app.nav.activePathClass : ''
+  - const activePathClass = !isActive && isParent ? 'nav__link--active-path' : ''

package/views/partials/link-list-navigation.pug

@@ -1,7 +1,7 @@
 include ../helper/mixins
 
 mixin linkListNav(elements=app.nav.elements, className='')
-    ul.nav(class=`${className}`)
+    ul.nav.nav--list(class=`${className}`)
         include ../helper/setup
-            li.nav-item
+            li.nav__item
                 +link(item, activeClass, activePathClass)