metalsmith-menu-plus

⚠️: This plugin is a fully functional proof-of-concept. It allows you to build a hierarchical navigation structure plus page breadcrumbs. However, it is not yet fully tested and may contain bugs. Use with caution.

Automatic hierarchical navigation generator for Metalsmith sites

Features

• Creates a nested navigation structure reflecting your content hierarchy
• Supports permalink-style URLs (/page/ instead of /page.html)
• Custom ordering via frontmatter or global configuration
• Breadcrumb generation for each page
• Automatic exclusion of draft content (draft: true)
• Flexible exclusion patterns for omitting files from navigation
• Automatic title generation from filenames

Installation

npm install metalsmith-menu-plus

Usage

This plugin follows the standard Metalsmith plugin pattern and can be used both with ESM and CommonJS.

IMPORTANT: This plugin must be used before the layout plugin in the Metalsmith build chain, because it expects HTML files.

ESM (preferred)

import metalsmith from 'metalsmith';
import markdown from 'metalsmith-markdown';
import layouts from 'metalsmith-layouts';
import navMenu from 'metalsmith-menu-plus';

metalsmith(__dirname)
  ...
  .use(markdown()) // Convert Markdown to HTML
  .use(navMenu({   // Then generate navigation
    metadataKey: 'siteNav',
    usePermalinks: true
  }))
  .use(layouts())  // Apply layouts
  .build((err) => {
    if (err) throw err;
    console.log('Build complete!');
  });

CommonJS

const metalsmith = require('metalsmith');
const markdown = require('metalsmith-markdown');
const layouts = require('metalsmith-layouts');
const navigationMenu = require('metalsmith-menu-plus');

metalsmith(__dirname)
  ...
  .use(markdown()) // Convert Markdown to HTML
  .use(navMenu({   // Then generate navigation
    metadataKey: 'siteNav',
    usePermalinks: true
  }))
  .use(layouts())  // Apply layouts
  .build((err) => {
    if (err) throw err;
    console.log('Build complete!');
  });

Options

| Option | Type | Default | Description | |--------------------|----------------------|---------------|----------------------------------------------------------------------------------------------------------| | metadataKey | String | 'navigation' | The key to use in the Metalsmith metadata where the navigation structure will be stored | | usePermalinks | Boolean | false | Whether to use permalink-style URLs (e.g., /page/ instead of /page.html) | | navIndex | Object | {} | Custom ordering for navigation items, with paths as keys and numeric indices as values | | sortBy | Function | null | Custom sorting function for navigation items at the same level with the same navIndex | | navExcludePatterns | Array | [] | Patterns (string, RegExp, or function) to exclude files from navigation | | rootPath | String | '/' | The root path to start building the navigation from (e.g., '/blog/' to only show blog navigation) |

Frontmatter Options

Individual pages can customize their navigation properties using frontmatter:

---
title: About Us
layout: page.njk
draft: true                    # Exclude from navigation (draft content)
navigation:
  navLabel: About Our Company  # Custom navigation label
  navIndex: 5                  # Custom order in navigation
  navExclude: true             # Exclude this page from navigation
---

Navigation Structure

The plugin adds a hierarchical navigation structure to the Metalsmith metadata, accessible via the configured metadataKey. The structure looks like:

[
  {
    title: "Home Page",
    path: "/",
    navIndex: 0,
    children: []
  },
  {
    title: "Blog",
    path: "/blog/",
    navIndex: 10,
    children: [
      {
        title: "First Post",
        path: "/blog/first-post/",
        navIndex: null,
        children: []
      }
    ]
  }
]

Breadcrumbs

The plugin also generates breadcrumbs for each file and adds them to the file's metadata. The breadcrumbs are accessible via:

navigation.breadcrumbs

Each breadcrumb is an object with a title and path property.

Active State Path

The plugin adds the current page's path to the file's navigation object, making it easy to detect the active page in templates:

navigation.path

This path can be compared with navigation item paths to highlight the active page in the navigation menu.

Template Usage

Basic Navigation Menu

{% if siteNav %}
  <nav>
    <ul>
      {% for item in siteNav %}
        <li>
          <a href="{{ item.path }}" {% if navigation.path === item.path %}class="active"{% endif %}>
            {{ item.title }}
          </a>
          
          {% if item.children.length > 0 %}
            <ul>
              {% for child in item.children %}
                <li>
                  <a href="{{ child.path }}" {% if navigation.path === child.path %}class="active"{% endif %}>
                    {{ child.title }}
                  </a>
                </li>
              {% endfor %}
            </ul>
          {% endif %}
          
        </li>
      {% endfor %}
    </ul>
  </nav>
{% endif %}

Breadcrumbs

{% if navigation.breadcrumbs and navigation.breadcrumbs.length > 1 %}
  <nav aria-label="Breadcrumb">
    <ol class="breadcrumbs">
      {% for crumb in navigation.breadcrumbs %}
        <li>
          {% if loop.last %}
            <span aria-current="page">{{ crumb.title }}</span>
          {% else %}
            <a href="{{ crumb.path }}">{{ crumb.title }}</a>
          {% endif %}
        </li>
      {% endfor %}
    </ol>
  </nav>
{% endif %}

Advanced Configuration

Section-Specific Navigation

You can create navigation that only shows a specific section:

// Main site navigation
.use(navigationMenu({
  metadataKey: 'siteNav',
  usePermalinks: true
}))

// Blog-specific navigation
.use(navigationMenu({
  metadataKey: 'blogNav',
  usePermalinks: true,
  rootPath: '/blog/'  // Only show blog section
}))

This is useful for creating specialized navigation for different sections of your site.

Custom Ordering

.use(navigationMenu({
  metadataKey: 'siteNav',
  usePermalinks: true,
  navIndex: {
    '/': 0,           // Home page first
    '/blog': 10,      // Blog section second
    '/about': 20      // About page third  
  },
  sortBy: (a, b) => {
    // Sort by title (applies to items with same navIndex)
    return a.title.localeCompare(b.title);
  }
}))

Custom Exclusion Rules

The plugin automatically excludes files with draft: true in their frontmatter. You can also define additional custom exclusion patterns:

.use(navigationMenu({
  metadataKey: 'siteNav',
  navExcludePatterns: [
    // Exclude specific paths
    'private/secret-page.html',
    // Exclude with regex
    /\/temp\//,
    // Exclude with custom function
    (path, file) => file && file.private === true
  ]
}))

Note: Files with draft: true are automatically excluded and don't need to be specified in navExcludePatterns.

Test Coverage

This plugin maintains high test coverage to ensure reliability. Current test coverage is displayed in the badge at the top of this README.

To run tests locally:

npm test

To view coverage details:

npm run coverage

Debug

This plugin uses the debug module for debugging. To enable debug logs, set the DEBUG environment variable:

DEBUG=metalsmith-menu-plus node your-metalsmith-build.js

CLI Usage

To use this plugin with the Metalsmith CLI, add it to your metalsmith.json file:

{
  "plugins": {
    "metalsmith-menu-plus": {
      "metadataKey": "siteNav",
      "usePermalinks": true,
      "navIndex": {
        "/": 0,
        "/blog": 10,
        "/about": 20
      },
      "rootPath": "/"
    }
  }
}

You can also use the plugin multiple times to create different navigation structures:

{
  "plugins": {
    "metalsmith-menu-plus#main": {
      "metadataKey": "siteNav",
      "usePermalinks": true,
      "rootPath": "/"
    },
    "metalsmith-menu-plus#blog": {
      "metadataKey": "blogNav",
      "usePermalinks": true,
      "rootPath": "/blog/"
    }
  }
}

License

MIT