[Feature request] Collections

[vralle]

Feature request

What is motivation or use case for adding/changing the behavior?

Efficient mass generation of homogeneous pages (e.g., gallery albums) from content files with front matter is a common need. At present, each entry typically requires its own template wiring, manual sorting, and manual pagination, which is repetitive, error‑prone, and difficult to scale. A first‑class “collections” facility would automate this flow: point to a content directory, define a data schema, sorting and pagination rules, and obtain fully rendered entry pages plus index pages.

Example album entry in Markdown with front matter:

---
layout: @src/layouts/album.html
title: Album title
description: album description.
image: ./entry-image.png
image_alt: The best entry image
gallery:
  - image: ./image-1.png
    alt: image 1 description
  - image: ./image-2.png
    alt: image 2 description
meta:
  description: Album meta description.
  socialImage: ./album-social-image.png
tags:
  - Cool
  - Easy
  - Fast
publishDate: 2014-08-27 12:50:00
slug: album-1
---

Entry text

Describe the solution you'd like

Add integrated “collections” support to HtmlBundlerPlugin so the plugin can:

• Scan a content directory and parse front matter from Markdown/HTML.
• Generate entry pages using the layout declared in front matter.
• Build collection index pages (with pagination) from a designated template.
• Provide configurable sorting, pagination, data validation via a schema, and slug generation.
• Optionally source entries from an external API (e.g., WordPress REST API) instead of local files.

Proposed configuration shape:

new HtmlBundlerPlugin({
  test: /\.html$/i,
  entry: {
   "gallery/index": {
     import: "src/pages/gallery/index.html",
     collection: {
        // Sorting for collection entries
        sort: (entries) => customSorting(entries),
        // Pagination: number per page or a custom function
        pagination: 10, // or (entries) => paginate(entries, { perPage: 10 })
        // Data source and processing rules
        content: {
          test: /\.md$/,
          path: "./src/content/gallery", // path to dir with entry files
          schema: (data) => customDataValidator(data), // e.g., zod
          slug: (entry) => customSlugFunction(entry), // default: derived from filename with limax
          layout: "@src/views/layout/album.html"
      },
      // Template context (illustrative):
      // collections.gallery.entries, collections.gallery.all, page.current, page.total, page.prev, page.next
    },
  },
});

Expected behavior:

• A page is generated for each discovered entry file, using a path derived from slug (or filename).
• The gallery index is rendered from the index template, e.g., /gallery/, with pagination at /gallery/page/2, /gallery/page/3, etc.
• Template context includes:
  • collections.gallery.entries (entries for the current page),
  • collections.gallery.all (all entries, if needed),
  • page (current page number, total pages, prev/next links),
  • all front matter fields (title, image, tags, publishDate, etc.).
• An external data source option enables static site generation directly from APIs (e.g., WordPress REST API) without intermediary scripts, bringing an experience comparable to Astro’s content collections and pagination.

Illustrative index template:

<!-- ./src/pages/gallery/index.html -->
<ul>
  <% for (const entry of collections.gallery.entries) { %>
    <li>
      <a href="/gallery/<%= entry.slug %>/"><%= entry.title %></a>
      <time datetime="<%= entry.publishDate %>"><%= entry.publishDate %></time>
    </li>
  <% } %>
</ul>

<nav>
  <% if (page.prev) { %><a href="<%= page.prev.href %>">Prev</a><% } %>
  <span>Page <%= page.current %> of <%= page.total %></span>
  <% if (page.next) { %><a href="<%= page.next.href %>">Next</a><% } %>
</nav>

Describe alternatives you've considered

• Astro content collections with built‑in sorting and pagination; trade‑off: switching from the current Webpack‑based pipeline.
• Custom scripts/loaders for parsing front matter, route generation, and pagination; trade‑off: bespoke maintenance and weaker integration with HtmlBundlerPlugin.
• Static site generators (Gatsby/Next SSG/Nuxt/Eleventy); trade‑off: ecosystem change and migration overhead.
• Manual lists, sorting, and pagination; trade‑off: time‑consuming, error‑prone, and hard to scale.

---

Appreciation for the useful project

• After the feature is implemented, do not forget to give a star ⭐

[webdiscus]

Тhe idea is cool, however the proposed "collections" feature goes far beyond the scope of html-bundler-webpack-plugin and would require implementing functionality similar to dedicated static site generators (Astro, Eleventy, etc.), which is a large and complex task maintained by many contributors over years.

The same can be achieved by more verbosely configuring multiple pages based on a single template and custom data set per page.

P.S.: I think I'll leave this ticket open. Maybe I'll come back to it when I have some free time for it.

[webdiscus]

As far as I understand, the "front matter" is something similar to the declaration of variables that are used in the template? Can be this passed as external data?
I did not quite understand the role of collection in the config, how should the plugin use it?

[webdiscus]

Cursory research

So, a ready-made Webpack plugin that scans a content directory, builds collections with pagination, and renders them via a template really doesn't exist. The implementing this inside HtmlBundlerPlugin would be almost like creating a new SSG within Webpack.

There are only partial solutions:

• Front matter loaders (frontmatter-markdown-loader, yaml-frontmatter-loader) can parse front matter from Markdown/HTML, but do not handle automatic page generation, indexes, or pagination.
• Static site generators built on Webpack (e.g., VuePress) provide this functionality, but they are full frameworks, not drop-in Webpack plugins.
• Custom scripts - many developers write their own scripts to generate .html files from content, and then let Webpack bundle the assets.

[vralle]

As far as I understand, the "front matter" is something similar to the declaration of variables that are used in the template?

Yes! Front matter is a block of metadata placed at the top of a Markdown or MDX file, typically written in YAML. It’s like a mini database entry embedded directly into your content file.

Benefits:

• Front matter is isolated from HTML, which keeps your content clean and portable.
• You don't mix layout logic or styling directly into your Markdown, just pure content and metadata.
• You store content and metadata together, making each file self-contained.
• No need for separate config files or external databases to manage titles, dates, tags, authors, etc.
• UI in vscode with type checking, SEO audit and more. See more: https://frontmatter.codes/

Example of Front matter UI in vscode:

Can be this passed as external data?

The problem is you can't extract data from md/mdx file and pass it to template.

Here is it my current preprocessor:

/**
 * Preprocessor with nunjucks
 * @see https://webdiscus.github.io/html-bundler-docs/plugin-options-preprocessor#custom-processing-function
 * @param {string} content Raw template content
 * @param {object} loaderContext
 * @param {"production"|"development"|"none"} loaderContext.mode Webpack mode
 * @param {string} loaderContext.rootContext Webpack context path
 * @param {string} loaderContext.resource Template file URL with query parameters.
 * @param {string} loaderContext.resourcePath Absolute template file path.
 * @param {object} loaderContext.data Custom template data (object or string)
 * @returns {string} Template content
 */
export const preprocessor = (content, loaderContext) => {
  const { rootContext, data } = loaderContext;

  const njk = nunjucks.configure(
    [
      path.join(projectPaths.src, "views"),
      projectPaths.src,
      rootContext,
    ],
    {
      autoescape: true,
      trimBlocks: true,
      noCache: true,
      watch: false,
    },
  );

  njk.addExtension("MarkdownTag", new MarkdownTag());

  return njk.renderString(content, data);
};

To use front matter data in a template, it typically requires parsing the Markdown tag, reading the file contents, extracting the front matter, and then passing the data to Nunjucks. There might be a more elegant way to handle this directly within Nunjucks, but I'm not deeply familiar with its internals.

Instead, I found it slightly more straightforward to write a script that reads the contents of a directory with Markdown files, processes the front matter using a validator, and then passes the result as external data into the plugin configuration, specifying the entry point programmatically.

Pros:

• The script is nearly compatible with Astro's collection configuration, making migration very simple.

Cons:

• Webpack needs to be restarted whenever front matter data changes.