@nera-static/plugin-popular-content

A plugin for the Nera static site generator that creates lists of popular content based on meta properties. Perfect for creating featured content sections, homepage teasers, or content sliders.

✨ Features

• Group content by any meta property (e.g., is_popular, is_featured)
• Configurable sorting (ascending or descending)
• Multiple content groups in a single configuration
• Access all grouped content via app.popularContent
• Includes ready-to-use Pug templates with BEM CSS methodology
• Template publishing system for easy customization
• 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-popular-content

Nera will automatically detect the plugin and apply the content grouping during the build.

⚙️ Configuration

The plugin uses config/popular-content.yaml to define which meta properties to track:

properties:
    - meta_property_name: is_popular
      order: desc
    - meta_property_name: is_home_teaser
      order: desc

• meta_property_name: The meta field to group by
• order: Sort order (asc or desc, defaults to asc)

🧩 Usage

Mark content in your markdown files

Add the configured meta properties to your pages:

---
title: Amazing Article
description: This article is really amazing
is_popular: 3
is_home_teaser: 1
---
# Amazing Article

Your content here...

---
title: Another Great Post
description: Another excellent read
is_popular: 1
is_home_teaser: 2
---
# Another Great Post

More content...

Access in your templates

The plugin makes grouped content available via app.popularContent:

// Display popular content
if app.popularContent.is_popular.length > 0
    section.popular-content
        h2 Popular Articles
        ul
            each item in app.popularContent.is_popular
                li
                    a(href=item.href) #{item.title}
                    p #{item.description}

// Display homepage teasers
if app.popularContent.is_home_teaser.length > 0
    section.home-teasers
        each item in app.popularContent.is_home_teaser
            article.teaser
                h3 #{item.title}
                p #{item.description}
                a(href=item.href) Read more

Available data structure

Each item in the grouped arrays contains:

{
    title: "Article Title",
    description: "Article description",
    href: "/path/to/article.html",
    is_popular: 3,
    content: "<h1>Article Title</h1><p>Content...</p>",
    // ... all other meta properties
}

🛠️ Publish Default Templates

Use the default templates provided by the plugin:

npx @nera-static/plugin-popular-content run publish-template

This copies templates to:

views/vendor/plugin-popular-content/
├── popular-content.pug
└── teaser.pug

Using the templates

Include them in your layouts:

// Basic popular content list
include views/vendor/plugin-popular-content/popular-content

// Teaser cards for homepage
include views/vendor/plugin-popular-content/teaser

Template customization

You can customize the copied templates or create your own based on the data structure provided by app.popularContent.

🎯 Use Cases

Homepage Featured Content

# config/popular-content.yaml
properties:
    - meta_property_name: is_featured
      order: desc

---
title: Featured Article
is_featured: 1
---

Content Sliders

properties:
    - meta_property_name: slider_priority
      order: desc

Multiple Content Sections

properties:
    - meta_property_name: is_trending
      order: desc
    - meta_property_name: is_recent
      order: desc
    - meta_property_name: is_recommended
      order: asc

🛠️ Template Publishing

Use the default templates provided by the plugin:

npx @nera-static/plugin-popular-content run publish-template

This copies the templates to:

views/vendor/plugin-popular-content/
├── popular-content.pug    # Standard popular content list
└── teaser.pug            # Homepage teaser cards

You can then include them in your layouts:

// Include popular content section
include /views/vendor/plugin-popular-content/popular-content.pug

// Include homepage teasers
include /views/vendor/plugin-popular-content/teaser.pug

🎨 BEM CSS Classes

The default templates use BEM (Block Element Modifier) methodology:

Popular Content Template:

• .popular-content - Main container
• .popular-content__title - Section title
• .popular-content__list - Content list
• .popular-content__item - List item
• .popular-content__link - Content link
• .popular-content__description - Item description
• .popular-content__date - Creation date

Teaser Template:

• .home-teasers - Main container
• .home-teasers__title - Section title
• .home-teasers__grid - Grid container
• .home-teasers__card - Individual teaser card
• .home-teasers__header - Card header
• .home-teasers__card-title - Card title
• .home-teasers__content - Card content area
• .home-teasers__description - Card description
• .home-teasers__footer - Card footer
• .home-teasers__link - Read more link

🧪 Development

npm install
npm test
npm run lint

Tests are powered by Vitest and cover:

• Content grouping and sorting functionality
• Template publishing logic and file overwrite prevention
• Configuration validation

🔄 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 getAppData() function to process page data and make popular content available via app.popularContent. Content is grouped by meta properties and sorted according to configuration.

Git Hooks

This project uses Husky for Git hooks:

• pre-commit: Runs linting (npm run lint)
• pre-push: Runs tests (npm test)

After cloning, activate the hooks:

git config core.hooksPath .husky

Tests use Vitest and Cheerio and cover:

• Content grouping by meta properties
• Sorting functionality (ascending/descending)
• Multiple property handling
• Content preservation in grouped items
• Template rendering with HTML structure validation
• Template publishing logic

🧑‍💻 Author

Michael Becker
https://github.com/seebaermichi

🔗 Links

• Plugin Repository
• NPM Package
• Nera Static Site Generator

📦 License

MIT