poops 1.2.3 → 1.2.4

package/README.md

@@ -70,13 +70,13 @@ or pass a custom config. This is useful when you have multiple environments:
 
 **CLI Options:**
 
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--build` | `-b` | Build the project and exit |
-| `--config <path>` | `-c` | Specify the config file |
-| `--port <number>` | `-p` | Specify the server port, overrides config |
-| `--livereload-port <number>` | `-l` | Specify the livereload port, overrides config |
-| `--base-url <path>` | `-u` | Set the base URL prefix for markup, overrides config |
+| Flag                         | Short | Description                                          |
+| ---------------------------- | ----- | ---------------------------------------------------- |
+| `--build`                    | `-b`  | Build the project and exit                           |
+| `--config <path>`            | `-c`  | Specify the config file                              |
+| `--port <number>`            | `-p`  | Specify the server port, overrides config            |
+| `--livereload-port <number>` | `-l`  | Specify the livereload port, overrides config        |
+| `--base-url <path>`          | `-u`  | Set the base URL prefix for markup, overrides config |
 
 The `--base-url` flag is particularly useful for CI/CD pipelines where the deploy path may differ per environment:
 
@@ -146,14 +146,8 @@ Just create a `poops.json` file in the root of your project and add the followin
       "title": "Poops",
       "description": "A super simple bundler for simple web projects."
     },
-    "data": [
-      "data/links.json",
-      "data/poops.yaml"
-    ],
-    "includePaths": [
-      "_layouts",
-      "_partials"
-    ]
+    "data": ["data/links.json", "data/poops.yaml"],
+    "includePaths": ["_layouts", "_partials"]
   },
   "copy": [
     {
@@ -375,13 +369,15 @@ Add `tokenPaths` to your styles config:
 
 ```json
 {
-  "styles": [{
-    "in": "src/scss/index.scss",
-    "out": "dist/css/styles.css",
-    "options": {
-      "tokenPaths": ["src/tokens"]
+  "styles": [
+    {
+      "in": "src/scss/index.scss",
+      "out": "dist/css/styles.css",
+      "options": {
+        "tokenPaths": ["src/tokens"]
+      }
     }
-  }]
+  ]
 }
 ```
 
@@ -459,9 +455,7 @@ You can also pass options to plugins using the tuple form:
     "in": "src/css/main.css",
     "out": "dist/css/main.css",
     "options": {
-      "plugins": [
-        ["autoprefixer", { "grid": true }]
-      ]
+      "plugins": [["autoprefixer", { "grid": true }]]
     }
   }
 }
@@ -538,13 +532,8 @@ Here is a sample markup configuration using the default Nunjucks engine:
       "title": "My Awesome Site",
       "description": "This is my awesome site"
     },
-    "data": [
-      "data/links.json",
-      "data/other.yaml"
-    ],
-    "includePaths": [
-      "_includes"
-    ],
+    "data": ["data/links.json", "data/other.yaml"],
+    "includePaths": ["_includes"],
     "baseURL": "/blog"
   }
 }
@@ -562,14 +551,8 @@ To use Liquid instead, set the `engine` property:
       "title": "My Awesome Site",
       "description": "This is my awesome site"
     },
-    "data": [
-      "_data/links.json",
-      "_data/other.yaml"
-    ],
-    "includePaths": [
-      "_layouts",
-      "_partials"
-    ]
+    "data": ["_data/links.json", "_data/other.yaml"],
+    "includePaths": ["_layouts", "_partials"]
   }
 }
 ```
@@ -580,17 +563,104 @@ If your project doesn't have markups, you can remove the `markup` property from
 
 Both engines support the same feature set (collections, pagination, search index, sitemap, custom tags, and filters). The main differences are in template syntax:
 
-| Feature | Nunjucks | Liquid |
-|---------|----------|--------|
-| File extension | `.njk` | `.liquid` |
-| Inheritance | `{% extends "base.html" %}` | `{% layout "base.liquid" %}` |
-| Default values | `{{ x or "fallback" }}` | `{{ x \| default: "fallback" }}` |
-| Contains check | `{% if "x" in items %}` | `{% if items contains "x" %}` |
-| Safe output | `{{ html \| safe }}` | `{{ html }}` (no escaping by default) |
-| Includes | `{% include "partial.njk" %}` | `{% render "partial.liquid" %}` |
+| Feature        | Nunjucks                      | Liquid                                |
+| -------------- | ----------------------------- | ------------------------------------- |
+| File extension | `.njk`                        | `.liquid`                             |
+| Inheritance    | `{% extends "base.html" %}`   | `{% layout "base.liquid" %}`          |
+| Default values | `{{ x or "fallback" }}`       | `{{ x \| default: "fallback" }}`      |
+| Contains check | `{% if "x" in items %}`       | `{% if items contains "x" %}`         |
+| Safe output    | `{{ html \| safe }}`          | `{{ html }}` (no escaping by default) |
+| Includes       | `{% include "partial.njk" %}` | `{% render "partial.liquid" %}`       |
 
 Both engines process `.html` and `.md` files in addition to their native extension.
 
+#### Collections & Pagination
+
+Collections turn a directory of pages into a sorted, optionally paginated list — blog posts, changelog entries, documentation. A collection maps to a direct subdirectory of your markup `in` directory: every `.html`, `.njk`, `.liquid` or `.md` file inside it (except the `index.*` file) becomes a collection item.
+
+There are two ways to declare a collection:
+
+**1. Front matter auto-discovery** — add `collection` to the front matter of the directory's index file:
+
+```yaml
+---
+title: Changelog
+collection: true
+paginate: 10
+sort: date
+---
+```
+
+`collection: true` uses the directory name as the collection name; a string (e.g. `collection: changelog`) names it explicitly. `paginate` and `sort` are optional.
+
+**2. Config** — list collections in the markup config. The name must match a subdirectory of `in`:
+
+```json
+{
+  "markup": {
+    "in": "src/markup",
+    "out": "dist",
+    "collections": [
+      "changelog",
+      {
+        "name": "blog",
+        "paginate": 5,
+        "sort": { "by": "title", "order": "asc" }
+      }
+    ]
+  }
+}
+```
+
+**Sorting.** By default items are sorted by `date`, newest first. `sort` can be a field name shorthand (`"sort": "title"`) or an object `{ "by": "field", "order": "asc" | "desc" }`. Sorting by `date` compares dates (default order `desc`); any other field compares alphabetically (default order `asc`).
+
+**Items.** Each item exposes its own front matter plus properties Poops adds:
+
+- `url` - the item's output path relative to the site root (e.g. `changelog/my-post.html`)
+- `title` - falls back to the file name if not set in front matter
+- `date` - falls back to the file's modification time if not set, with a build warning. Set a real `date` in front matter — mtime is meaningless on CI checkouts (git clone resets it), so undated posts will reshuffle between deploys.
+- `wordcount`, `fileName`, `filePath`, `collection`
+
+An item with `published: false` in its front matter is excluded from the collection and its page is not built.
+
+**Using collections in templates.** Every collection is available as a global variable named after it, on every page:
+
+```nunjucks
+{% for post in changelog.items %}
+  <a href="{{ relativePathPrefix }}{{ post.url }}">{{ post.title }}</a> — {{ post.date | date }}
+{% endfor %}
+```
+
+**Pagination.** With `paginate: N` set, the collection's index file is rendered once per page of N items: page 1 to `out/changelog/index.html`, page 2 to `out/changelog/2/index.html`, and so on. Inside the index template the collection object carries the page state:
+
+| Variable                    | Description                                             |
+| --------------------------- | ------------------------------------------------------- |
+| `pageItems`                 | the items on the current page                           |
+| `pageNumber` / `totalPages` | current page (1-based) / total page count               |
+| `pageUrl`                   | URL of the current page (`changelog`, `changelog/2`, …) |
+| `nextPage` / `nextPageUrl`  | next page number / URL, `null` on the last page         |
+| `prevPage` / `prevPageUrl`  | previous page number / URL, `null` on the first page    |
+
+From the example site's `changelog/index.html`:
+
+```nunjucks
+{% for post in changelog.pageItems %}
+  <div class="post">
+    <h2><a href="{{ relativePathPrefix }}{{ post.url }}">{{ post.title }}</a></h2>
+    <div class="date">{{ post.date | date }}</div>
+    {{ post.description }}
+  </div>
+{% endfor %}
+
+{% if changelog.totalPages > 1 %}
+  {% if changelog.nextPageUrl %}<a href="{{ relativePathPrefix }}{{ changelog.nextPageUrl }}">Next</a>{% endif %}
+  {{ changelog.pageNumber }} of {{ changelog.totalPages }}
+  {% if changelog.prevPageUrl %}<a href="{{ relativePathPrefix }}{{ changelog.prevPageUrl }}">Previous</a>{% endif %}
+{% endif %}
+```
+
+Item pages themselves are compiled like any other markup file, preserving the directory structure: `src/markup/changelog/my-post.md` → `dist/changelog/my-post.html`. A collection directory without an index file still builds its items and exposes the collection to templates — only the paginated listing pages are skipped.
+
 #### Custom Tags
 
 ##### image
@@ -602,11 +672,13 @@ Poops can generate responsive `<img>` elements with `srcset` attributes. Image p
 **`{% image %}` tag** — generates a full `<img>` element:
 
 Nunjucks:
+
 ```nunjucks
 {% image 'static/photo.jpg', alt='Hero', class='hero-img', sizes='(max-width: 640px) 100vw, 50vw' %}
 ```
 
 Liquid:
+
 ```liquid
 {% image 'static/photo.jpg', alt: 'Hero', class: 'hero-img', sizes: '(max-width: 640px) 100vw, 50vw' %}
 ```
@@ -635,21 +707,31 @@ Output:
 - Defaults: `sizes="100vw"`, `loading="lazy"`
 - Falls back to a plain `<img src="...">` if no variants are found
 
+**[poops-images](https://github.com/stamat/poops-images) integration:** if a `.poops-images-cache.json` compile cache is found in the output directory (poops-images writes one next to the images it generates), Poops reads variants from it instead of scanning the directory. On top of the scan behavior above, the cache gives you:
+
+- `width` and `height` attributes on the `<img>` element (exact dimensions from the cache — prevents layout shift). Pass your own `width`/`height` kwargs to override.
+- Correct `src` when the source format was converted (e.g. `photo.heic` → `photo.jpg`), even when there are no size variants.
+- Named sizes (`photo-thumb-200w.jpg`) and preprocessed outputs (`photo-blurred-640w.jpg`) are kept out of the srcset — they are crops and effects with their own aspect ratios. Only plain `{name}-{width}w.{ext}` variants (from the poops-images `widths` option) are used.
+- EXIF metadata via the `exif` filter (see below).
+
 ##### googleFonts
 
 Generates Google Fonts `<link>` tags with preconnect hints. Accepts an array of font names (strings) or font objects with weight/italic options.
 
 Nunjucks (supports inline arrays):
+
 ```nunjucks
 {% googleFonts ["Open Sans", "Roboto"] %}
 ```
 
 Liquid (pass a variable — inline arrays are not supported in Liquid syntax):
+
 ```liquid
 {% googleFonts fonts %}
 ```
 
 Where `fonts` is defined in a data file (e.g. `fonts.json`):
+
 ```json
 ["Open Sans", "Roboto"]
 ```
@@ -674,7 +756,7 @@ With specific weights and italics (Nunjucks):
 With specific weights and italics (Liquid — via data file):
 
 ```json
-["DM Sans", {"name": "Poppins", "weights": [400, 700], "ital": true}]
+["DM Sans", { "name": "Poppins", "weights": [400, 700], "ital": true }]
 ```
 
 Font object options:
@@ -749,6 +831,7 @@ All filters are available in both engines. The only syntax difference is how arg
   - Liquid: `{{ changelog.items | groupby: "author" }}` or `{{ changelog.items | groupby: "date", "year" }}`
 
   Example — group posts by year:
+
   ```nunjucks
   {% set byYear = changelog.items | groupby("date", "year") %}
   {% for group in byYear %}
@@ -772,6 +855,69 @@ All filters are available in both engines. The only syntax difference is how arg
 
 Returns: `static/photo-320w.webp 320w, static/photo-640w.webp 640w, static/photo-960w.webp 960w`
 
+- `exif` — returns the EXIF metadata object for an image from the [poops-images](https://github.com/stamat/poops-images) compile cache (`.poops-images-cache.json` in the output directory), or `null` if there is no cache or no EXIF data. The object includes camera (`make`, `model`, `lensModel`), exposure (`fNumber`, `exposure.formatted`, `iso`, `focalLength35mm`), `dateTime`, and `gps` (`latitude.formatted`, `longitude.formatted`, `altitude`, and a ready-made `googleMapsUrl`).
+
+  Example — a photo with date and location caption:
+
+  ```nunjucks
+  {% set meta = 'static/photo.jpeg' | exif %}
+  <figure>
+    {% image 'static/photo.jpeg', alt='Sendai at dusk' %}
+    {% if meta %}
+      <figcaption>
+        {{ meta.dateTime | date("MMMM D, YYYY") }}
+        {% if meta.gps %}
+          — <a href="{{ meta.gps.googleMapsUrl }}">{{ meta.gps.latitude.formatted }}, {{ meta.gps.longitude.formatted }}</a>
+        {% endif %}
+        {% if meta.model %}· {{ meta.model }}{% endif %}
+      </figcaption>
+    {% endif %}
+  </figure>
+  ```
+
+- `images` — lists all images under a site-relative directory from the [poops-images](https://github.com/stamat/poops-images) compile cache. Returns an array of `{ path, width, height, date, exif, outputs }` objects, or an empty array if there is no cache:
+  - `path` — site-relative source path, feeds straight into the `{% image %}` tag
+  - `date` — `exif.dateTime` when the photo has EXIF, file modification time otherwise — so sorting and grouping work for every image
+  - `outputs` — every generated file for the image (site-relative), useful for picking LQIP or preprocessed variants
+  - Pass a subdirectory (`'images/2025'`) to scope the list
+
+  Combined with `groupby`, engine-native sorting and the `{% image %}` tag, a photo gallery is a pure template concern:
+
+  Nunjucks:
+
+  ```nunjucks
+  {% for group in 'images' | images | sort(reverse=true, attribute='date') | groupby("date", "year") %}
+    <h2>{{ group.key }}</h2>
+    <div class="grid">
+      {% for img in group.items %}
+        <figure>
+          {% image img.path, alt='', sizes='(max-width: 640px) 50vw, 25vw' %}
+          {% if img.exif and img.exif.gps %}
+            <figcaption>
+              <a href="{{ img.exif.gps.googleMapsUrl }}">📍</a> {{ img.date | date("MMM D, YYYY") }}
+            </figcaption>
+          {% endif %}
+        </figure>
+      {% endfor %}
+    </div>
+  {% endfor %}
+  ```
+
+  Liquid:
+
+  ```liquid
+  {% assign imgs = 'images' | images | sort: 'date' | reverse %}
+  {% assign groups = imgs | groupby: "date", "year" %}
+  {% for group in groups %}
+    <h2>{{ group.key }}</h2>
+    <div class="grid">
+      {% for img in group.items %}
+        <figure>{% image img.path, alt: '' %}</figure>
+      {% endfor %}
+    </div>
+  {% endfor %}
+  ```
+
 #### Search Index & Sitemap
 
 Poops can automatically generate a JSON search index and/or an XML sitemap from your compiled pages. Both are generated in a single pass during the markup compilation phase.
@@ -842,6 +988,39 @@ All front matter fields are passed through to the index automatically. Internal
 
 Pages with `published: false` in their front matter are excluded from both outputs.
 
+### Images (optional)
+
+Process and optimize images — compression, responsive size variants, format conversion (WebP/AVIF), crops and EXIF extraction — by running [poops-images](https://github.com/stamat/poops-images) as part of the build. This is what feeds the `{% image %}` tag, the `exif`/`images` filters and the `.poops-images-cache.json` compile cache described in [Custom Tags](#custom-tags) and [Custom Filters](#custom-filters).
+
+poops-images (and its `sharp` dependency) is **not** bundled with Poops. Install it in your project only if you use the `images` config:
+
+```bash
+npm i poops-images
+```
+
+If the `images` key is present but poops-images is not installed, Poops logs a warning and skips image processing — the rest of the build still runs.
+
+The `images` value is a poops-images config object (see the [poops-images options reference](https://github.com/stamat/poops-images#configuration)). The most common keys:
+
+- `in` — source images directory
+- `out` — output directory (keep it distinct from `in`, and outside your watched source, so generated variants don't retrigger the build)
+- `sizes` — responsive widths to generate
+- `format` — target formats (e.g. `["webp"]`, or `"smart"` to keep whichever of JPEG/WebP is smaller)
+- `verbose` - defaults to `false`, so you get a single `[image]` summary line (count + time) instead of one log per file. Set `"verbose": true` to restore the per-file logs.
+
+```json
+{
+  "images": {
+    "in": "src/images",
+    "out": "dist/images",
+    "sizes": [{ "width": 640 }, { "width": 1280 }],
+    "format": "smart"
+  }
+}
+```
+
+Images are processed **before** markup, so `{% image %}` and the `images` filter always read a fresh cache. In watch mode, changing a source image reprocesses it and recompiles markup; deleting one removes its generated variants and updates the galleries that referenced it. Custom handlers and composite overlays resolve relative to your `poops.json`.
+
 ### Copy
 
 Configuration entry to copy files or directories - copy your static files like images and fonts, for instance, from `src` to `dist` directory. This feature was added to enable moving static files if you deploy GitHub pages via a GitHub action. If you don't want to use this feature, simply exclude the `copy` property from your config file.
@@ -945,6 +1124,18 @@ Live reload options:
 
 - `port` - the port on which the livereload server will run
 - `exclude` - an array of files and directories to exclude from livereload
+- `extraExts` - an array of extra file extensions (without the dot) that trigger a browser refresh, added to the defaults
+- `exts` - an array of file extensions that replaces the default list entirely
+
+By default a refresh is triggered by changes to: `html`, `css`, `js`, `png`, `gif`, `jpg`, `php`, `php5`, `py`, `rb`, `erb`, `coffee`. If you work with other file types, for example Slim or Nunjucks templates, add them:
+
+```json
+{
+  "livereload": {
+    "extraExts": ["slim", "njk"]
+  }
+}
+```
 
 `livereload` can only be `true`, which means that it will run on the default port (`35729`) or you can specify a port:
 
@@ -1011,23 +1202,6 @@ Same as `watch` property, `includePaths` accepts an array of paths to include. I
 }
 ```
 
-## Todo
-
-- [ ] Run esbuild for each input path individually if there are multiple input paths
-- [ ] Styles `in` should be able to support array of inputs like we have it on scripts
-- [ ] Build a cli config creation helper tool. If the user doesn't have a config file, we can ask them a few questions and create a config file for them. Create Yeoman generator for poops projects.
-- [x] Add nunjucks static templating
-  - [x] Refactor nunjucks implementation
-  - [x] Complete documentation for nunjucks
-  - [x] Add markdown support
-  - [x] Front Matter support
-  - [x] Future implementation: posts and custom collections, so we can have a real static site generator
-  - [x] Collection pagination system
-  - [x] Post published toggle
-  - [x] RSS and ATOM generation for collections
-  - [x] Support for images and creating srcsets
-- [x] Add Liquid template engine as a swappable alternative to Nunjucks
-
 ## Why?
 
 Why doesn't anyone maintain GULP anymore? Why does Parcel hate config files? Why are Rollup and Webpack so complex to setup for simple tasks? Vite???? What's going on?

package/lib/copy.js

@@ -4,7 +4,8 @@ import {
   pathIsDirectory,
   mkDir,
   copyDirectory,
-  buildTime
+  buildTime,
+  toPosix
 } from './utils/helpers.js'
 import fs from 'node:fs'
 import path from 'node:path'
@@ -91,7 +92,8 @@ export default class Copy {
       copyPaths.out = path.join(copyPaths.out, inBaseName)
     }
 
-    file = file.replace(copyPaths.in, copyPaths.out)
+    // Watcher paths arrive with native separators, config `in` uses `/`
+    file = toPosix(file).replace(copyPaths.in, copyPaths.out)
 
     const outputFilePath = path.join(process.cwd(), file)
 

package/lib/images.js

@@ -0,0 +1,57 @@
+import log from './utils/log.js'
+
+// Runs poops-images (https://github.com/stamat/poops-images) as a regular
+// runner when a `config.images` block is present AND the package is installed.
+// poops-images stays an optional peer dependency — sharp never becomes a hard
+// dep of poops. The markup engines read the cache poops-images writes, so this
+// runner must execute before markups.compile().
+export default class Images {
+  constructor(config) {
+    this.config = config
+    this.processor = null // lazily created on first compile()
+    this.disabled = false // no images config, or poops-images not installed
+  }
+
+  async init() {
+    if (this.processor || this.disabled) return
+    if (!this.config.images) { this.disabled = true; return }
+
+    let ImageProcessor
+    try {
+      ImageProcessor = (await import('poops-images')).default
+    } catch (err) {
+      // Native ESM throws ERR_MODULE_NOT_FOUND; CJS-style/jest resolvers throw
+      // MODULE_NOT_FOUND. Either means the optional dep simply isn't installed.
+      if (err.code === 'ERR_MODULE_NOT_FOUND' || err.code === 'MODULE_NOT_FOUND') {
+        log({ tag: 'image', warn: true, text: 'images config found but poops-images is not installed — run: npm i poops-images' })
+        this.disabled = true
+        return
+      }
+      throw err
+    }
+
+    // Quiet by default inside poops — one summary line instead of per-image
+    // logs drowning the other runners. Opt back in with "verbose": true.
+    // A bad images config throws here, propagating to the build's step() so
+    // the build is marked failed rather than silently skipping images.
+    this.processor = new ImageProcessor({ verbose: false, ...this.config.images })
+  }
+
+  async compile() {
+    await this.init()
+    if (!this.processor) return
+    const stats = await this.processor.processAll()
+    // Route through poops' log so hasLoggedErrors() flips the build exit code.
+    // Older poops-images without the errors field: undefined is falsy, no-op.
+    if (stats.errors > 0) {
+      log({ tag: 'image', error: true, text: `${stats.errors} image(s) failed to process` })
+    }
+  }
+
+  // Watch mode: a deleted source image removes its generated variants + cache entry.
+  async remove(file) {
+    await this.init()
+    if (!this.processor) return
+    this.processor.removeSource(file)
+  }
+}

package/lib/markup/collections.js

@@ -2,12 +2,13 @@ import fs from 'node:fs'
 import { globSync } from 'glob'
 import path from 'node:path'
 import log from '../utils/log.js'
-import { mkDir } from '../utils/helpers.js'
+import { mkDir, toPosix } from '../utils/helpers.js'
 import { replaceOutExtensions, getRelativePathPrefix, getPageUrl, parseFrontMatter, wordcount } from './helpers.js'
 
 export function getSingleCollectionData(markupInDir, collectionName) {
   const collectionData = []
-  globSync(path.join(process.cwd(), markupInDir, collectionName, '**/*.+(html|njk|liquid|md)'), { ignore: ['**/index.+(html|njk|liquid|md)'] }).forEach((file) => {
+  // glob patterns must use `/` — on Windows `\` is an escape character
+  globSync(toPosix(path.join(process.cwd(), markupInDir, collectionName, '**/*.+(html|njk|liquid|md)')), { ignore: ['**/index.+(html|njk|liquid|md)'] }).forEach((file) => {
     let frontMatter = {}
 
     let content = ''
@@ -23,13 +24,16 @@ export function getSingleCollectionData(markupInDir, collectionName) {
     if (frontMatter.published === false) return
 
     if (!frontMatter.date) {
-      frontMatter.date = fs.statSync(file).ctime.toISOString().slice(0, 16)
+      // mtime is only a local-dev approximation — git clone resets it, so CI
+      // builds date undated posts "now". The warning is the real fix.
+      frontMatter.date = fs.statSync(file).mtime.toISOString().slice(0, 16)
+      log({ tag: 'markup', warn: true, text: 'No date in front matter, falling back to file mtime:', link: file })
     }
     frontMatter.wordcount = wordcount(content)
     frontMatter.fileName = path.basename(file)
     frontMatter.filePath = path.relative(process.cwd(), file)
     frontMatter.collection = collectionName
-    frontMatter.url = path.join(collectionName, path.basename(frontMatter.filePath))
+    frontMatter.url = toPosix(path.join(collectionName, path.basename(frontMatter.filePath)))
 
     frontMatter.url = replaceOutExtensions(frontMatter.url)
 
@@ -43,7 +47,7 @@ export function getSingleCollectionData(markupInDir, collectionName) {
 }
 
 export function collectionAutoDiscovery(markupInDir) {
-  const indexFiles = globSync(path.join(process.cwd(), markupInDir, '/**/index.+(html|njk|liquid|md)'))
+  const indexFiles = globSync(toPosix(path.join(process.cwd(), markupInDir, '/**/index.+(html|njk|liquid|md)')))
 
   const collectionData = {}
 
@@ -180,11 +184,25 @@ export function buildCollectionPaginationData(collectionData) {
 }
 
 export function getCollectionIndexFile(markupInDir, collectionName) {
-  const indexFiles = globSync(path.join(process.cwd(), markupInDir, collectionName, 'index.+(html|njk|liquid|md)'))
+  const indexFiles = globSync(toPosix(path.join(process.cwd(), markupInDir, collectionName, 'index.+(html|njk|liquid|md)')))
   if (indexFiles.length === 0) return null
   return indexFiles[0]
 }
 
+export function pruneStalePaginationDirs(collectionName, markupInDir, markupOutDir, keepPages) {
+  const outDir = path.join(process.cwd(), markupOutDir, collectionName)
+  if (!fs.existsSync(outDir)) return
+
+  for (const entry of fs.readdirSync(outDir)) {
+    const pageNumber = parseInt(entry, 10)
+    // pagination only ever writes out/<name>/2..totalPages/
+    if (String(pageNumber) !== entry || pageNumber < 2 || pageNumber <= keepPages) continue
+    // numeric dir mirrored from a real source dir — not pagination output
+    if (fs.existsSync(path.join(process.cwd(), markupInDir, collectionName, entry))) continue
+    fs.rmSync(path.join(outDir, entry), { recursive: true, force: true })
+  }
+}
+
 export function generateCollectionPaginationPages(collectionData, markupInDir, markupOutDir, compileEntryFn, baseURL) {
   if (!collectionData) return []
 
@@ -199,6 +217,11 @@ export function generateCollectionPaginationPages(collectionData, markupInDir, m
       collection.pages = [collection.items]
     }
 
+    // a shrunk page count (or removed index) leaves stale out/<name>/N/ dirs
+    pruneStalePaginationDirs(collection.name, markupInDir, markupOutDir, file ? collection.totalPages : 1)
+
+    if (!file) continue
+
     for (let i = 0; i < collection.totalPages; i++) {
       const pageNumber = i + 1
       const pageUrl = pageNumber === 1 ? collection.name : `${collection.name}/${pageNumber}`
@@ -226,8 +249,6 @@ export function generateCollectionPaginationPages(collectionData, markupInDir, m
       const fromPath = path.join(process.cwd(), markupOutDir)
       const markupOutDirFull = path.dirname(markupOut)
 
-      mkDir(markupOutDirFull)
-
       const context = {
         ...collectionData,
         [collectionName]: pageSnapshot,
@@ -235,11 +256,11 @@ export function generateCollectionPaginationPages(collectionData, markupInDir, m
         _url: getPageUrl(markupOut)
       }
 
-      if (!file) {
-        continue
-      }
-
-      const compilePromise = compileEntryFn(file, context).then(({ result }) => {
+      // mkDir only when a page is actually written: no empty pagination dirs
+      // for index-less or unpublished (skipped) collection indexes
+      const compilePromise = compileEntryFn(file, context).then(({ result, skipped }) => {
+        if (skipped) return
+        mkDir(markupOutDirFull)
         fs.writeFileSync(markupOut, result)
       })
       compilePromises.push(compilePromise)