@nera-static/plugin-page-navigation

A plugin for the Nera static site generator that creates a navigation between sibling pages or uses custom navigation definitions. Lightweight, flexible, and easy to integrate in any layout.

✨ Features

• Automatically adds navigation based on sibling pages
• Supports custom navigation via frontmatter
• Optional sorting via position meta field
• Configurable active class for the current page
• Includes a ready-to-use Pug view

🚀 Installation

Install the plugin in your Nera project:

npm install @nera-static/plugin-page-navigation

Nera will automatically detect the plugin and apply the page navigation metadata during the build.

🛠️ Usage

Automatic sibling navigation

If you don’t define a page_navigation property in your markdown file, the plugin will automatically collect sibling pages from the same directory.

You can define a position field to control the sorting:

---
title: Page A
type: page
position: 1
---

Custom navigation

To override the navigation, define it in the frontmatter like this:

---
title: Page with custom nav
type: page
page_navigation:
    - href: /index.html
      name: Home
    - href: /contact.html
      name: Contact
---

🛠️ Publish Default Template

Use the default template provided by the plugin:

npx @nera-static/plugin-page-navigation run publish-template

This copies the template to:

views/vendor/plugin-page-navigation/page-navigation.pug

💡 The file contains multiple layout options. Uncomment the version that fits your needs.

Using the template in your layout

Once published, include the navigation in your Pug templates:

include views/vendor/plugin-page-navigation/page-navigation

The plugin provides three navigation styles:

• +simpleNav - Basic horizontal navigation (default)
• +pipeSeparated - Navigation with pipe separators
• +linkList - Unordered list navigation

Available metadata

The plugin adds the following data to each page's meta object:

meta.pageNav = {
    activeClass: 'active', // CSS class for current page
    elements: [
        // Array of navigation items
        {
            name: 'Page Title',
            href: '/path/to/page.html',
            current: true, // true for current page
            position: 1,
        },
    ],
}

⚙️ Configuration

# config/page-navigation.yaml
active_page_nav_class: 'active'

This class will be applied to the currently active page in the navigation.

🧪 Development

npm install
npm test
npm run lint
npm run publish-template  # Publish templates to your project

Tests use Vitest and cover:

• Sibling navigation detection
• Custom overrides
• Sorting via position
• Active class behavior

🔄 Compatibility

• Nera v4.1.0+: Full compatibility with latest static site generator
• Node.js 18+: Modern JavaScript features and ES modules
• Plugin Utils v1.1.0+: Enhanced plugin utilities integration

🏗️ Architecture

This plugin uses the getMetaData() function to process page data and inject sibling navigation information. It automatically detects pages in the same directory and provides multiple template formats.

🎨 BEM CSS Classes

The plugin uses BEM (Block Element Modifier) methodology:

• .page-nav - Main navigation block
• .page-nav__item - Navigation list items
• .page-nav__link - Navigation links
• .page-nav__link--active - Active page link
• .page-nav--list - List-style navigation
• .page-nav--pipe-separated - Pipe-separated navigation

🧑‍💻 Author

Michael Becker
https://github.com/seebaermichi

🔗 Links

• Plugin Repository
• NPM Package
• Nera Static Site Generator
• Plugin Documentation

📦 License

MIT