@nera-static/plugin-simple-page-list

A plugin for the Nera static site generator that creates filtered page lists based on directory paths. Ideal for blog post listings, news sections, or content categories grouped and sorted chronologically.

✨ Features

• Filter pages by one or more directory paths
• Supports flat or grouped page lists (app.pageList or app.pageList.<key>)
• Automatic chronological sorting (configurable)
• Custom sorting by date, title, or any frontmatter field
• Access filtered lists globally in templates
• Includes ready-to-use Pug templates using BEM CSS methodology
• Configurable "read more" link text
• 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-simple-page-list

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

⚙️ Configuration

Define the filter settings in config/simple-page-list.yaml.

🔹 Option 1: Single path (legacy)

page_path: /posts
more_link_text: Read more

• page_path: Directory to include pages from
• more_link_text: Label for the "read more" link (optional)

🔹 Option 2: Multiple paths (grouped output)

page_paths:
    - /recipes/lunch
    - /recipes/breakfast
    - path: /blog
      key: blogPosts
      sortBy: title
      sortOrder: ascending
sortBy: date
sortOrder: descending
more_link_text: Read more
exclude_pages:
    - /recipes/lunch/index.html

• page_paths: Array of paths (either strings or objects)
  • If a string, the last folder segment becomes the key (e.g. /recipes/lunch → lunch)
  • If an object, you can override the key, sortBy, or sortOrder
• sortBy: Field to sort by (date, title, etc.)
• sortOrder: ascending or descending
• Top-level sortBy/sortOrder apply to all unless overridden per entry
• exclude_pages: Array of rendered pages which should not be included in the page list (e.g. /recipes/lunch/index.html)

🧩 Usage

Content Frontmatter

Ensure your pages are located in the configured directories and include required metadata:

---
title: Delicious Pasta
description: A quick and easy pasta recipe.
date: 2025-01-15
---

Supported date formats:

• 2025-01-15 (ISO)
• 15.01.2025 (German-style)
• Any JS-valid date string

If date is missing, Nera’s createdAt will be used as a fallback.

Access in templates

Legacy usage (single path config):

if app.pageList && app.pageList.length > 0
  section.page-list
    h2 Recent Posts
    each page in app.pageList
      article.page-list__item
        h3: a(href=page.href) #{page.title}
        if page.description
          p #{page.description}
        a.page-list__more-link(href=page.href) #{page.moreLinkText}

Grouped usage (multiple paths):

if app.pageList.blogPosts
  h2 Blog
  each post in app.pageList.blogPosts
    article
      h3: a(href=post.href) #{post.title}

if app.pageList.lunch
  h2 Lunch Recipes
  each recipe in app.pageList.lunch
    h3: a(href=recipe.href) #{recipe.title}

📊 Output Structure

Depending on configuration, the plugin injects one of the following:

1. Flat array (legacy):

app.pageList = [
  {
    ...meta
    date: 1705276800000,
    moreLinkText: "Read more"
  },
  ...
]

2. Grouped object:

app.pageList = {
    lunch: [{ moreLinkText, date, ...meta }],
    blogPosts: [{ moreLinkText, date, ...meta }],
}

🛠️ Template Publishing

Use the default template provided by the plugin:

npx @nera-static/plugin-simple-page-list run publish-template

This will copy:

views/vendor/plugin-simple-page-list/
└── simple-page-list.pug

You can then include it in your layout:

include /views/vendor/plugin-simple-page-list/simple-page-list

🎨 Styling

The default template uses BEM-style class names:

.page-list {
}
.page-list__title {
}
.page-list__item {
}
.page-list__header {
}
.page-list__item-title {
}
.page-list__link {
}
.page-list__description {
}
.page-list__footer {
}
.page-list__more-link {
}

🧪 Testing & Development

npm install
npm test
npm run lint

Tests use Vitest and cover:

• Filtering by directory path
• Sorting by date, title, etc.
• Grouped and flat output modes
• Correct fallback behavior and robustness
• Template publishing logic

🧑‍💻 Author

Michael Becker
https://github.com/seebaermichi

🔗 Links

• Plugin Repository
• NPM Package
• Nera Static Site Generator

🧩 Compatibility

• Nera: v4.1.0+
• Node.js: >= 18
• Plugin API: Uses getAppData() for injecting filtered page lists

📦 License

MIT