@nera-static/plugin-tags

A plugin for the Nera static site generator that creates tag clouds, tag links, and tag overview pages from page tags. Perfect for content organization, taxonomy management, and content discovery.

✨ Features

Filter and organize content by tags
Automatic tag cloud generation with alphabetical sorting
Clickable tag links for each page
Individual tag overview pages with all tagged content
Access all tag data globally via app.tagCloud and meta.tagLinks
Includes ready-to-use Pug templates with BEM CSS methodology
Template publishing system for easy customization
Configurable tag separators, paths, and layouts
Lightweight and zero-runtime overhead
Full compatibility with Nera v4.1.0+

🚀 Installation

Install the plugin in your Nera project:

npm install @nera-static/plugin-tags

Nera will automatically detect the plugin and apply tag processing during the build.

⚙️ Configuration

The plugin uses config/tags.yaml to configure tag behavior:

# Meta property name containing tags (default: 'tags')
meta_property_name: tags

# Tag separator (default: ',')
tag_separator: ','

# Base path for tag overview pages (default: '/tags')
tag_overview_path: '/tags'

# Layout template for tag overview pages (default: 'pages/default.pug')
tag_overview_layout: 'pages/default.pug'

# Additional meta properties for tag overview pages
tag_overview_meta:
  description: 'Browse content by tag'
  layout: 'pages/tag-layout.pug'

# Optional: Tag-specific images
tag_overview_default_image: '/images/tags/default.jpg'
tag_overview_javascript_image: '/images/tags/js-logo.jpg'
tag_overview_css_image: '/images/tags/css-logo.jpg'

meta_property_name: The meta field containing tags (defaults to tags)
tag_separator: Character used to separate tags (defaults to ,)
tag_overview_path: Base URL path for tag pages (defaults to /tags)
tag_overview_layout: Layout template for tag overview pages
tag_overview_meta: Additional meta properties for tag pages
tag_overview_*_image: Tag-specific or default images

🧩 Usage

Mark content with tags

Add tags to your Markdown files using frontmatter:

---
title: Getting Started with JavaScript
description: Learn the basics of JavaScript programming
tags: javascript, programming, web development, frontend
---

# Getting Started with JavaScript

Your content here...

---
title: CSS Grid Layout Guide
description: Master CSS Grid for modern web layouts
tags: css, layout, web development, design
---

# CSS Grid Layout Guide

More content...

Access in your templates

The plugin makes tag data available in multiple ways:

1. Global tag cloud via `app.tagCloud`

Display all available tags:

// Display tag cloud
if app.tagCloud.length > 0
    section.tag-cloud
        h2 Browse by Tag
        each tag in app.tagCloud
            a.tag-cloud__item(href=tag.href) #{tag.name}

2. Page-specific tag links via `meta.tagLinks`

Show tags for the current page:

// Display page tags
if meta.tagLinks.length > 0
    section.tag-links
        span Tags:
        each tag in meta.tagLinks
            a.tag-links__item(href=tag.href) #{tag.name}

3. Tag overview pages via generated routes

Each tag gets its own page with tagged content:

// In tag overview layout
section.tag-overview
    header.tag-overview__header
        h1.tag-overview__title #{meta.title}

    if meta.taggedPages.length > 0
        section.tag-overview__content
            each page in meta.taggedPages
                article.tag-overview__item
                    h2.tag-overview__item-title #{page.meta.title}
                    p.tag-overview__item-description #{page.meta.description}
                    a.tag-overview__item-link(href=page.meta.href) Read more

Available data structure

Tag cloud items (app.tagCloud):

[
    {
        name: "javascript",
        href: "/tags/javascript.html"
    },
    {
        name: "css",
        href: "/tags/css.html"
    }
]

Page tag links (meta.tagLinks):

[
    {
        name: "javascript",
        href: "/tags/javascript.html"
    },
    {
        name: "programming",
        href: "/tags/programming.html"
    }
]

Tag overview page data (meta.taggedPages):

[
    {
        meta: {
            title: "Getting Started with JavaScript",
            description: "Learn the basics...",
            href: "/articles/js-basics.html",
            createdAt: Date
        }
    }
]

🛠️ Template Publishing

Use the default templates provided by the plugin:

npx @nera-static/plugin-tags run publish-template

This copies template files to your project:

views/vendor/plugin-tags/
├── pages/
│   └── tag-overview.pug
└── partials/
    ├── tag-cloud.pug
    └── tag-links.pug

Using the templates

Include the templates in your Pug files:

// In any layout or page - display tag cloud
include /vendor/plugin-tags/partials/tag-cloud

// Display page-specific tags
include /vendor/plugin-tags/partials/tag-links

// For tag overview pages
include /vendor/plugin-tags/pages/tag-overview

🎨 Styling with BEM CSS

The templates use BEM (Block Element Modifier) methodology for CSS classes.

📊 Generated URLs

Tag overview pages are automatically generated with clean URLs:

/tags/javascript.html - All JavaScript-related content
/tags/css.html - All CSS-related content
/tags/web-development.html - All web development content

Tags with spaces or special characters are URL-safe (converted to lowercase, spaces become hyphens).

🧪 Development

npm install
npm test
npm run lint

Testing

The plugin includes comprehensive tests covering:

Unit tests for tag cloud generation, tag links, and page generation
Integration tests for template publishing functionality
Template rendering tests for all included Pug templates with BEM classes

Tests validate tag extraction, deduplication, sorting, URL generation, and template rendering with various data scenarios.

🔧 Advanced Configuration

Custom Tag Separators

# Use pipe separator instead of comma
tag_separator: '|'

---
title: My Article
tags: javascript|react|frontend
---

Custom Meta Property

# Use 'categories' instead of 'tags'
meta_property_name: categories

---
title: My Article
categories: javascript, react, frontend
---

Custom Paths and Layouts

# Custom tag overview configuration
tag_overview_path: '/topics'
tag_overview_layout: 'layouts/topic-page.pug'
tag_overview_meta:
  layout: 'layouts/topic-page.pug'
  description: 'Browse articles by topic'
  image: '/images/topics-banner.jpg'