poops 1.2.3 → 1.3.0

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 }]]
     }
   }
 }
@@ -517,7 +511,7 @@ Then use Tailwind utility classes directly in your markup templates. Tailwind v4
 
 ### Markups
 
-- `engine` (optional) - the template engine to use. Can be `"nunjucks"` (default) or `"liquid"`. [Nunjucks](https://mozilla.github.io/nunjucks/) is a Mozilla template engine inspired by Jinja2. [Liquid](https://liquidjs.com/) is a Shopify-compatible template engine. Both engines support the same tags, filters, collections, search index, and sitemap features documented below.
+- `engine` (optional) - the template engine to use. Can be `"nunjucks"` (default) or `"liquid"`. [Nunjucks](https://mozilla.github.io/nunjucks/) is a Mozilla template engine inspired by Jinja2. [Liquid](https://liquidjs.com/) is a Shopify-compatible template engine. Both engines support the same tags, filters, collections, search index, sitemap, and navigation tree features documented below.
 - `in` - the input path, can be a directory or a file path, but please just use it as a directory path for now. All files in this directory will be processed and the structure of the directory will be preserved in the output directory with exception to directories that begin with an underscore `_` will be ignored.
 - `out` - the output path, can be only a directory path (for now)
 - `site` (optional) - global data that will be available to all templates in the markup directory. Like site title, description, social media links, etc. You can then use this data in your templates `{{ site.title }}` for instance.
@@ -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"]
   }
 }
 ```
@@ -578,19 +561,158 @@ If your project doesn't have markups, you can remove the `markup` property from
 
 #### Nunjucks vs Liquid
 
-Both engines support the same feature set (collections, pagination, search index, sitemap, custom tags, and filters). The main differences are in template syntax:
+Both engines support the same feature set (collections, pagination, search index, sitemap, navigation tree, 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.
 
+#### Custom Engines
+
+The `engine` option also accepts a module specifier — an npm package name or a path relative to your project root. The module's default export must be an engine class:
+
+```json
+{
+  "markup": {
+    "in": "src/markup",
+    "out": "dist",
+    "engine": "poops-shopify"
+  }
+}
+```
+
+An engine class implements this contract (see [`lib/markup/engines/`](lib/markup/engines/) for the two built-in reference implementations):
+
+```js
+export default class MyEngine {
+  constructor(templatesDir, includePaths, options) {}      // options: { autoescape }
+  get fileExtension() { return '.liquid' }                 // native template extension
+  get indexableExtensions() { return new Set(['.html']) }  // extensions eligible for search index/nav
+  get markupExtensions() { return 'html|liquid|md' }       // glob alternation of processed extensions
+  registerFilters({ timeDateFormat, markupOut }) {}
+  registerTags(getOutputDir) {}
+  setGlobal(key, value) {}
+  removeGlobal(key) {}
+  async render(templatePath, context) { return 'html' }    // templatePath is an absolute file path
+  async renderString(source, context) { return 'html' }
+}
+```
+
+Optionally, an engine may implement `replaceOutExtensions(outputPath)` to control how source extensions map to output extensions (the default maps `.md`/`.njk`/`.liquid` to `.html`).
+
+The easiest starting point is extending a built-in engine — deep imports are intentionally supported for this:
+
+```js
+import LiquidEngine from 'poops/lib/markup/engines/liquid.js'
+
+export default class MyEngine extends LiquidEngine {
+  registerFilters(opts) {
+    super.registerFilters(opts)
+    this.engine.registerFilter('shout', (str) => String(str).toUpperCase())
+  }
+}
+```
+
+#### 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 %}
+```
+
+Or use the `{% pagination %}` shorthand tag (available in both engines), which renders Previous/Next links and a "page of total" counter — with `relativePathPrefix` applied — and outputs nothing when there is only one page:
+
+```nunjucks
+{% pagination changelog %}
+```
+
+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 +724,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 +759,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 +808,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 +883,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,11 +907,74 @@ 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`
 
-#### Search Index & Sitemap
+- `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:
 
-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.
+  ```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>
+  ```
 
-To enable, add `searchIndex` and/or `sitemap` to your markup config:
+- `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 & Navigation
+
+Poops can automatically generate a JSON search index, an XML sitemap and a navigation tree from your compiled pages. All are generated in a single pass during the markup compilation phase.
+
+To enable, add `searchIndex`, `sitemap` and/or `nav` to your markup config:
 
 ```json
 {
@@ -842,6 +1040,138 @@ 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.
 
+**Navigation tree** builds your page hierarchy as sidebar-ready data, exposed two ways: as the `nav` template global (loaded automatically, always reflecting the current build) and as a nested JSON file for client-side rendering. Subpages nest automatically from URL structure: `guide/index.md` becomes a parent node and `guide/getting-started.md`, `guide/advanced/config.md` become its (and its subsections') children. Add `nav` to your markup config:
+
+```json
+{
+  "markup": {
+    "in": "src/markup",
+    "out": "dist",
+    "options": {
+      "nav": "nav.json"
+    }
+  }
+}
+```
+
+The string shorthand sets the output filename. For docs sites, use the object form:
+
+```json
+{
+  "nav": {
+    "output": "nav.json",
+    "root": "docs",
+    "collections": "index",
+    "home": false
+  }
+}
+```
+
+**Navigation options:**
+
+- `output` — output filename, written to the markup output directory
+- `collections` — how to treat collection pages (default `true`):
+  - `true` — include every collection page, nested under its collection
+  - `false` — exclude all collection pages (drops a blog's posts from the sidebar)
+  - `["docs", ...]` — allowlist; only these collections' pages are included (non-collection pages are always kept)
+  - `"index"` — include only each collection's landing page as a single leaf, not its posts
+- `home` — `false` drops the site's root index page (url `""`) from the tree (default `true`)
+- `root` — scope the tree to a subdirectory (e.g. `"docs"`); its children are emitted at the top level and the section's own index page is pinned first as the overview link. URLs are kept full (`docs/getting-started`), so the homepage is naturally excluded
+
+**Front matter fields** that shape the tree:
+
+- `order` — a number that sorts a page within its sibling level (optional). Pages without `order` fall to the bottom, sorted alphabetically by title — so a hand-authored docs sequence (`1`, `2`, `3`) wins over alphabetical. This applies to the homepage too: give it `order: 0` in its front matter to pin it to the top, otherwise it sorts last like any page without `order`.
+- `nav: false` — hide a page from the sidebar (it stays in the search index and sitemap).
+- `navTitle` — a sidebar label that overrides `title`.
+
+**Navigation output format** — each node has a `title`, a `url` (omitted on synthesized section nodes that have no index page of their own), an `order` when set, and `children` when it has subpages:
+
+```json
+[
+  { "title": "Guide", "url": "guide", "order": 1, "children": [
+    { "title": "Getting Started", "url": "guide/getting-started", "order": 1 },
+    { "title": "Advanced", "url": "guide/advanced", "children": [
+      { "title": "Config", "url": "guide/advanced/config" }
+    ]}
+  ]}
+]
+```
+
+Pages with `published: false` or `nav: false` are excluded. If nothing survives filtering, an empty array `[]` is written so consumers never have to special-case a missing file.
+
+**Rendering the sidebar.** The tree is arbitrarily deep, so render it with a recursive template. The `nav` global is built from front matter in a pre-pass before templating, so it always reflects the current build — no need to load the generated `nav.json` back in via `data` (which would be one build behind). The written `nav.json` is for client-side rendering (`fetch('/nav.json')`). Prefix each `url` with `relativePathPrefix` so links resolve from any page depth.
+
+Nunjucks — a self-recursing macro:
+
+```njk
+{% macro navtree(items) %}
+<ul>
+  {% for item in items %}
+  <li>
+    {% if item.url != null %}<a href="{{ relativePathPrefix }}{{ item.url }}">{{ item.title }}</a>
+    {% else %}<span>{{ item.title }}</span>{% endif %}
+    {% if item.children %}{{ navtree(item.children) }}{% endif %}
+  </li>
+  {% endfor %}
+</ul>
+{% endmacro %}
+
+{{ navtree(nav) }}
+```
+
+Note the `!= null` check: the homepage node's `url` is an empty string (a valid link — `relativePathPrefix` resolves it), while synthesized section nodes have no `url` at all. A plain `{% if item.url %}` would wrongly demote the homepage to a `<span>`. Node titles already have `navTitle` applied, so `{{ item.title }}` is all you need.
+
+Liquid — a partial that recurses via `render` (save as `_partials/navtree.liquid`). Liquid treats empty strings as truthy, so the plain `if` is safe here:
+
+```liquid
+<ul>
+  {% for item in items %}
+  <li>
+    {% if item.url %}<a href="{{ relativePathPrefix }}{{ item.url }}">{{ item.title }}</a>
+    {% else %}<span>{{ item.title }}</span>{% endif %}
+    {% if item.children %}{% render 'navtree', items: item.children, relativePathPrefix: relativePathPrefix %}{% endif %}
+  </li>
+  {% endfor %}
+</ul>
+```
+
+```liquid
+{% render 'navtree', items: nav, relativePathPrefix: relativePathPrefix %}
+```
+
+### 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 +1275,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 +1353,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,9 +92,10 @@ 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)
+    const outputFilePath = path.resolve(process.cwd(), file)
 
     if (pathExists(outputFilePath)) {
       if (pathIsDirectory(outputFilePath)) {