poops 1.1.0 → 1.2.0

package/README.md

@@ -28,15 +28,18 @@ It uses a simple config file where you define your input and output paths and it
 
 - Bundles SCSS/SASS to CSS
 - Uses [dart-sass](https://sass-lang.com/dart-sass) for SCSS/SASS bundling
+- Design token support — import JSON tokens (W3C DTCG & Style Dictionary) as SCSS variables or maps
+- PostCSS pipeline — use any PostCSS plugin including [Tailwind CSS](https://tailwindcss.com/)
 - Bundles JS/TS/JSX/TSX to IIFE/ESM/CJS
 - Uses [esbuild](https://esbuild.github.io/) for bundling and transpiling JS/TS/JSX/TSX to IIFE/ESM/CJS
+- React pre-rendering (Reactor) — renders React components to HTML at build time for static sites with optional hydration
 - Optional JS and CSS minification using [esbuild](https://esbuild.github.io/)
 - Can produce minified code simultaneously with non-minified code! (cause I always forget to minify my code for production)
 - Supports source maps only for non minified - non production code (optional)
 - Supports multiple input and output paths
 - Resolves node modules
 - Can add a templatable banner to output files (optional)
-- Static site generation with [nunjucks](https://mozilla.github.io/nunjucks/) templating, with blogging option (optional)
+- Static site generation with swappable template engines: [Nunjucks](https://mozilla.github.io/nunjucks/) (default) or [Liquid](https://liquidjs.com/) — with blogging option (optional)
 - Has a configurable local server (optional)
 - Rebuilds on file changes (optional)
 - Live reloads on file changes (optional)
@@ -77,7 +80,7 @@ If you have installed Poops locally you can run it with `npx poops` or `npx 💩
 
 ## Configuration
 
-Configuring Poops is simple 😌. Let's presume that we have a `example/src/scss` and `example/src/js` directories and we want to bundle the files into `example/dist/css` and `example/dist/js`. If you also have markup files, you can use [nunjucks](https://mozilla.github.io/nunjucks/) templating engine to generate HTML files from your templates. Let's presume that we have a `example/src/markup` directory and we want to generate HTML files in the root of the your directory.
+Configuring Poops is simple 😌. Let's presume that we have a `example/src/scss` and `example/src/js` directories and we want to bundle the files into `example/dist/css` and `example/dist/js`. If you also have markup files, you can use [Nunjucks](https://mozilla.github.io/nunjucks/) (default) or [Liquid](https://liquidjs.com/) templating engine to generate HTML files from your templates. Let's presume that we have a `example/src/markup` directory and we want to generate HTML files in the root of the your directory.
 
 Just create a `poops.json` file in the root of your project and add the following (you can see this sample config in this repo's root):
 
@@ -96,6 +99,18 @@ Just create a `poops.json` file in the root of your project and add the followin
       }
     }
   ],
+  "reactor": [
+    {
+      "component": "example/src/js/App.jsx",
+      "inject": "app_html",
+      "in": "example/src/js/app-hydrate.jsx",
+      "out": "example/dist/js/app-hydrate.js",
+      "options": {
+        "minify": true,
+        "target": "es2019"
+      }
+    }
+  ],
   "styles": [
     {
       "in": "example/src/scss/index.scss",
@@ -108,22 +123,21 @@ Just create a `poops.json` file in the root of your project and add the followin
     }
   ],
   "markup": {
+    "engine": "nunjucks",
     "in": "example/src/markup",
     "out": "/",
-    "options": {
-      "site": {
-        "title": "Poops",
-        "description": "A super simple bundler for simple web projects."
-      },
-      "data": [
-        "example/src/markup/data/links.json",
-        "example/src/markup/data/poops.yaml"
-      ],
-      "includePaths": [
-        "example/src/markup/_layouts",
-        "example/src/markup/_partials"
-      ]
-    }
+    "site": {
+      "title": "Poops",
+      "description": "A super simple bundler for simple web projects."
+    },
+    "data": [
+      "data/links.json",
+      "data/poops.yaml"
+    ],
+    "includePaths": [
+      "_layouts",
+      "_partials"
+    ]
   },
   "copy": [
     {
@@ -142,7 +156,7 @@ Just create a `poops.json` file in the root of your project and add the followin
 }
 ```
 
-All config properties are optional except `scripts`, `styles` or `markups`. You have to specify at least one of them. If you don't have anything to consume, you won't poop. 💩
+All config properties are optional except `scripts`, `styles`, `postcss` or `markups`. You have to specify at least one of them. If you don't have anything to consume, you won't poop. 💩
 
 You can freely remove the properties that you don't need. For example, if you don't want to run a local server, just remove the `serve` property from the config.
 
@@ -218,26 +232,26 @@ Setting `jsx` to `automatic` uses React's JSX runtime (React 17+), so you don't
 
 As noted earlier, if you don't want to bundle scripts, just remove the `scripts` property from the config.
 
-### React SSG (Static Site Generation)
+### Reactor (React Pre-rendering)
 
-SSG renders React components to HTML at build time, then hydrates them on the client. This means pages load with pre-rendered content instead of an empty `<div>`.
+The `reactor` config key defines React components that are pre-rendered to HTML at build time (SSG) and optionally hydrated on the client. This is a separate pipeline from `scripts` — reactor entries have their own build step, watcher path, and logging tag.
 
-Each SSG entry has the following properties:
+Each reactor entry has the following properties:
 
-- `component` — the file that default-exports a React component (rendered server-side)
-- `in` — the client entry file for hydration (bundled for browser)
-- `out` — output path for the client bundle
-- `inject` — Nunjucks variable name for the rendered HTML
-- `options` — esbuild options (applied to the client bundle, same as `scripts` options)
+- `component` — the file that default-exports a React component (rendered at build time with `renderToString`)
+- `inject` — template global variable name for the rendered HTML (available in both Nunjucks and Liquid)
+- `in` (optional) — client entry file for hydration (bundled for the browser)
+- `out` (optional) — output path for the client bundle
+- `options` (optional) — esbuild options for the client bundle (same as script entries: `minify`, `format`, `target`, `sourcemap`, etc.)
 
 ```json
 {
-  "ssg": [
+  "reactor": [
     {
       "component": "src/js/App.jsx",
+      "inject": "app_html",
       "in": "src/js/app-hydrate.jsx",
       "out": "dist/js/app-hydrate.js",
-      "inject": "app_html",
       "options": {
         "minify": true,
         "target": "es2019"
@@ -247,23 +261,38 @@ Each SSG entry has the following properties:
 }
 ```
 
-In your Nunjucks templates, use the `inject` name to insert the rendered HTML:
+For backwards compatibility, `"ssg"` is also accepted as a config key — it is treated as an alias for `"reactor"`.
+
+In your templates, use the `inject` name to insert the rendered HTML:
 
 ```html
 <div id="root">{{ app_html | safe }}</div>
 <script src="js/app-hydrate.min.js"></script>
 ```
 
+If you only need server-side rendering without client hydration, omit `in` and `out`:
+
+```json
+{
+  "reactor": [
+    {
+      "component": "src/js/App.jsx",
+      "inject": "app_html"
+    }
+  ]
+}
+```
+
 **How it works:**
 
 1. Poops bundles the component with `react-dom/server` for Node.js and calls `renderToString`
-2. The rendered HTML is stored and made available as a Nunjucks global variable
-3. The client entry is bundled for the browser (same as a regular `scripts` entry)
+2. The rendered HTML is stored and made available as a template global variable
+3. If `in`/`out` are specified, the client entry is bundled for the browser
 4. At runtime, React hydrates the pre-rendered HTML, making it interactive
 
-SSG runs after Styles but before Scripts and Markups in the build pipeline. Poops does not need `react` or `react-dom` as its own dependency — they are resolved from your project's `node_modules`.
+Poops does not need `react` or `react-dom` as its own dependency — they are resolved from your project's `node_modules`. In watch mode, changes to files in the reactor component's directory trigger re-rendering and client re-bundling. Markup is recompiled only when the rendered output actually changes. Changes to other JS/TS files only trigger the scripts pipeline — the two are independent.
 
-In watch mode, changes to JSX/TSX files trigger SSG re-rendering followed by a markup recompile.
+**Note:** If you don't need server-side pre-rendering, you can bundle a React app entirely through the regular `scripts` pipeline — just point `in` to your `.jsx`/`.tsx` entry file and use `createRoot` on the client. The `reactor` config is only needed when you want build-time HTML rendering with optional hydration.
 
 ### Styles
 
@@ -278,6 +307,9 @@ Styles are bundled with [Dart Sass](https://sass-lang.com/dart-sass). You can sp
 - `sourcemap` - whether to generate sourcemaps or not, sourcemaps are generated only for non-minified files since they are useful for debugging. Default is `false`
 - `minify` - whether to minify the output or not, minification is performed by `esbuild`. Default is `false`
 - `justMinified` - whether you want to have a minified file as output only. Removes the non-minified file from the output. Useful for production builds. Defaults to `false`.
+- `tokenPaths` - a string or array of directory paths containing JSON design token files. Enables the [`sass-token-importer`](https://github.com/stamat/sass-token-importer) which lets you `@use` JSON tokens directly in SCSS. Supports [W3C DTCG](https://design-tokens.github.io/community-group/format/) and [Style Dictionary](https://amzn.github.io/style-dictionary/) formats with auto-detection.
+- `tokenOutput` - output mode for design tokens: `"variables"` (default) generates flat SCSS variables, `"map"` generates nested Sass maps.
+- `resolveAliases` - whether to resolve `{path.to.token}` alias references in design tokens. Default is `true`.
 
 `styles` property can accept an array of style configurations or just a single style configuration. If you want to bundle multiple styles, just add them to the `styles` array:
 
@@ -306,49 +338,476 @@ Styles are bundled with [Dart Sass](https://sass-lang.com/dart-sass). You can sp
 }
 ```
 
+#### Design Tokens
+
+You can import JSON design token files directly into your SCSS using the `token:` prefix. Define your tokens in JSON once and use them as SCSS variables — no manual variable files to keep in sync.
+
+Given a token file `src/tokens/colors.json`:
+
+```json
+{
+  "color": {
+    "$type": "color",
+    "primary": { "$value": "#0066cc" },
+    "secondary": { "$value": "#ff6600" },
+    "link": { "$value": "{color.primary}" }
+  }
+}
+```
+
+Add `tokenPaths` to your styles config:
+
+```json
+{
+  "styles": [{
+    "in": "src/scss/index.scss",
+    "out": "dist/css/styles.css",
+    "options": {
+      "tokenPaths": ["src/tokens"]
+    }
+  }]
+}
+```
+
+Then use the `token:` prefix in your SCSS:
+
+```scss
+@use "token:colors" as c;
+
+.btn {
+  color: c.$color-primary;
+}
+.btn:hover {
+  color: c.$color-secondary;
+}
+a {
+  color: c.$color-link; // resolved from {color.primary} → #0066cc
+}
+```
+
+For Sass maps instead of flat variables, set `"tokenOutput": "map"`:
+
+```scss
+@use "sass:map";
+@use "token:colors" as c;
+
+.btn {
+  color: map.get(c.$color, primary);
+}
+```
+
 As noted earlier, if you don't want to bundle styles, just remove the `styles` property from the config.
 
-### Markups 🚧
+### PostCSS (optional)
+
+Process CSS files with [PostCSS](https://postcss.org/) and any PostCSS plugins. This is a separate pipeline from Styles (Sass) — use it for tools like [Tailwind CSS](https://tailwindcss.com/), [Autoprefixer](https://github.com/postcss/autoprefixer), or any other PostCSS plugin.
 
-Poops can generate static pages for you. This feature is still under development, but available for testing from the v1.0.2. Your markup is templated with [nunjucks](https://mozilla.github.io/nunjucks/). You can specify multiple markup directories to template. **It's currently recommended to specify only one markup directory since this feature is still WIP 🚧.** Each markup directory has the following properties:
+PostCSS and its plugins are **not** bundled with Poops. You need to install them in your project:
 
+```bash
+npm i -D postcss
+```
+
+Each PostCSS entry has the following properties:
+
+- `in` - the input CSS file path
+- `out` - the output path, can be a directory or a file path
+- `options` - options for the pipeline
+
+**Options:**
+
+- `plugins` - an array of PostCSS plugin names to load. Each entry can be a string (plugin name) or a tuple `["plugin-name", { options }]` for passing options to the plugin.
+- `minify` - whether to minify the output using `esbuild`. Default is `false`
+- `justMinified` - output only the minified file. Default is `false`
+
+`postcss` property can accept an array of configurations or a single configuration:
+
+```json
+{
+  "postcss": {
+    "in": "src/css/main.css",
+    "out": "dist/css/main.css",
+    "options": {
+      "plugins": ["@tailwindcss/postcss"],
+      "minify": true
+    }
+  }
+}
+```
+
+You can also pass options to plugins using the tuple form:
+
+```json
+{
+  "postcss": {
+    "in": "src/css/main.css",
+    "out": "dist/css/main.css",
+    "options": {
+      "plugins": [
+        ["autoprefixer", { "grid": true }]
+      ]
+    }
+  }
+}
+```
+
+**Build order:** PostCSS runs after Styles and Markups in the build pipeline. This means PostCSS plugins can reference the compiled markup output (e.g. Tailwind scanning HTML for utility classes). In watch mode, PostCSS is re-triggered after Styles or Markups recompile.
+
+#### Tailwind CSS Example
+
+The `example-tailwind/` directory demonstrates using Tailwind CSS v4 with Poops. To run it:
+
+```bash
+npm i -D postcss @tailwindcss/postcss tailwindcss
+node poops.js -c example-tailwind/poops.json
+```
+
+The example config (`example-tailwind/poops.json`):
+
+```json
+{
+  "postcss": {
+    "in": "example-tailwind/src/css/main.css",
+    "out": "example-tailwind/dist/css/main.css",
+    "options": {
+      "plugins": ["@tailwindcss/postcss"],
+      "minify": true
+    }
+  },
+  "markup": {
+    "in": "example-tailwind/src/markup",
+    "out": "example-tailwind/dist",
+    "site": {
+      "title": "Poops + Tailwind",
+      "description": "A Tailwind CSS example for Poops"
+    },
+    "includePaths": ["_layouts", "_partials"]
+  },
+  "serve": { "port": 4041, "base": "/example-tailwind/dist" },
+  "livereload": true,
+  "watch": ["example-tailwind/src"]
+}
+```
+
+The CSS entry file (`src/css/main.css`) simply imports Tailwind:
+
+```css
+@import "tailwindcss";
+```
+
+Then use Tailwind utility classes directly in your markup templates. Tailwind v4 auto-detects content sources, so no `tailwind.config.js` is needed.
+
+**Using Sass + Tailwind together:** If you want both Sass and Tailwind, keep them as separate pipelines writing to separate output files. The Sass pipeline compiles `.scss` to CSS, while the PostCSS pipeline handles Tailwind independently. They don't need to chain into each other unless you want PostCSS to post-process the Sass output (e.g. with Autoprefixer) — in that case, point `postcss.in` to the Sass output file and `postcss.out` to a different file so the original Sass output is preserved for re-processing.
+
+### 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.
 - `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.
 - `data` (optional) - is an array of JSON or YAML data files, that once loaded will be available to all templates in the markup directory. If you provide a path to a file for instance `links.json` with a `facebook` property, you can then use this data in your templates `{{ links.facebook }}`. The base name of the file will be used as the variable name, with spaces, dashes and dots replaced with underscores. So `the awesome-links.json` will be available as `{{ the_awesome_links.facebook }}` in your templates. The root directory of the data files is `in` directory. So if you have a `data` directory in your `in` directory, you can specify the data files like this `data: ["data/links.json"]`. The same goes for the YAML files.
-- `includePaths` - an array of paths to directories that will be added to the nunjucks include paths. Useful if you want to separate template partials and layouts. For instance, if you have a `_includes` directory with a `header.njk` partial that you want to include in your markup, you can add it to the include paths and then include the templates like this `{% include "header.njk" %}`, without specifying the full path to the partial. This will change in the future, to provide better ignore and include patterns for the markup directories.
+- `includePaths` - an array of paths to directories that will be added to the template engine's include paths. Useful if you want to separate template partials and layouts. For instance, if you have a `_includes` directory with a `header.njk` (or `header.liquid`) partial that you want to include in your markup, you can add it to the include paths and then include the templates like this `{% include "header.njk" %}`, without specifying the full path to the partial.
 
 **💡 NOTE:** If, for instance, you are building a simple static onepager for your library, and want to pass a version variable from your `package.json`, Poops automatically reads your `package.json` if it exists in your working directory and sets the global variable `package` to the parsed JSON. So you can use it in your markup files, for example like this: `{{ package.version }}`.
 
-Here is a sample markup configuration:
+Here is a sample markup configuration using the default Nunjucks engine:
 
-```JSON
+```json
+{
+  "markup": {
+    "in": "src/markup",
+    "out": "dist",
+    "site": {
+      "title": "My Awesome Site",
+      "description": "This is my awesome site"
+    },
+    "data": [
+      "data/links.json",
+      "data/other.yaml"
+    ],
+    "includePaths": [
+      "_includes"
+    ]
+  }
+}
+```
+
+To use Liquid instead, set the `engine` property:
+
+```json
 {
-  "markups": {
+  "markup": {
+    "engine": "liquid",
+    "in": "src/liquid",
+    "out": "dist",
+    "site": {
+      "title": "My Awesome Site",
+      "description": "This is my awesome site"
+    },
+    "data": [
+      "_data/links.json",
+      "_data/other.yaml"
+    ],
+    "includePaths": [
+      "_layouts",
+      "_partials"
+    ]
+  }
+}
+```
+
+If your project doesn't have markups, you can remove the `markup` property from the config entirely. No code will be executed for this property.
+
+#### 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:
+
+| 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 Tags
+
+##### image
+
+Poops can generate responsive `<img>` elements with `srcset` attributes. Image processing (resize, format conversion) is handled externally — Poops discovers the generated variants on disk and produces the correct HTML markup.
+
+**Naming convention:** Your image tool should output variants as `{name}-{width}w.{ext}`. For example, given `photo.jpg`, the expected variants are: `photo-320w.jpg`, `photo-640w.jpg`, `photo-320w.webp`, `photo-640w.webp`, etc.
+
+**`{% 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' %}
+```
+
+Output:
+
+```html
+<img
+  src="static/photo-640w.jpg"
+  srcset="
+    static/photo-320w.webp 320w,
+    static/photo-640w.webp 640w,
+    static/photo-960w.webp 960w
+  "
+  sizes="(max-width: 640px) 100vw, 50vw"
+  alt="Hero"
+  class="hero-img"
+  loading="lazy"
+/>
+```
+
+- Scans the output directory for files matching `{name}-{width}w.{ext}`
+- Groups by format, prefers `avif` > `webp` > original format for srcset
+- Uses the middle-sized variant as `src` fallback
+- Prepends `relativePathPrefix` automatically
+- Defaults: `sizes="100vw"`, `loading="lazy"`
+- Falls back to a plain `<img src="...">` if no variants are found
+
+##### 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"]
+```
+
+Output:
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link
+  href="https://fonts.googleapis.com/css2?family=Open+Sans&family=Roboto&display=swap"
+  rel="stylesheet"
+/>
+```
+
+With specific weights and italics (Nunjucks):
+
+```nunjucks
+{% googleFonts ["DM Sans", {name: "Poppins", weights: [400, 700], ital: true}] %}
+```
+
+With specific weights and italics (Liquid — via data file):
+
+```json
+["DM Sans", {"name": "Poppins", "weights": [400, 700], "ital": true}]
+```
+
+Font object options:
+
+- `name` — font family name
+- `weights` — array of weight values (e.g. `[400, 700]`)
+- `ital` — set to `true` to include italic variants
+- `display` — font-display strategy, defaults to `swap` (Nunjucks only, as a keyword argument)
+
+##### highlight
+
+Syntax-highlights code blocks at build time using [highlight.js](https://highlightjs.org/), eliminating layout shift caused by client-side highlighting. Code is pre-highlighted in the HTML output — you only need the highlight.js CSS theme on the client, not the JS.
+
+**`{% highlight %}` tag** — wraps a code block with syntax highlighting (same syntax in both engines):
+
+```
+{% highlight 'javascript' %}
+const greet = (name) => {
+  return `Hello, ${name}!`;
+};
+{% endhighlight %}
+```
+
+Output:
+
+```html
+<pre><code class="hljs language-javascript"><span class="hljs-keyword">const</span> greet = <span class="hljs-function">...</span></code></pre>
+```
+
+The language argument is optional. If omitted, highlight.js will attempt to auto-detect the language.
+
+**Markdown code fences** are also highlighted automatically at build time:
+
+````md
+```json
+{ "name": "poops" }
+```
+````
+
+Registered languages: `javascript`/`js`, `typescript`/`ts`, `css`, `scss`, `html`, `xml`, `json`, `bash`/`sh`, `shell`, `python`/`py`, `ruby`/`rb`, `php`, `java`, `c`, `cpp`, `csharp`/`cs`, `go`, `rust`/`rs`, `yaml`/`yml`, `markdown`/`md`, `sql`, `diff`.
+
+#### Custom Filters
+
+All filters are available in both engines. The only syntax difference is how arguments are passed: Nunjucks uses parentheses `| filter("arg")`, Liquid uses a colon `| filter: "arg"`.
+
+- `slugify` — slugifies a string. Usage: `{{ "My Awesome Title" | slugify }}` will output `my-awesome-title`
+
+- `jsonify` — serializes a value to JSON. Usage: `{{ myObject | jsonify }}`
+
+- `markdown` — renders a markdown string to HTML. Usage: `{{ "**bold**" | markdown }}`
+
+- `date` — formats a date string. Uses [dayjs](https://day.js.org/) format tokens. A default format can be set via the `timeDateFormat` config option.
+  - Nunjucks: `{{ "2024-01-15" | date("MMMM D, YYYY") }}`
+  - Liquid: `{{ "2024-01-15" | date: "MMMM D, YYYY" }}`
+
+- `concat` — returns a new array with the value appended (does not mutate the original):
+  - Nunjucks: `{{ items | concat("c") }}`
+  - Liquid: `{{ items | concat: "c" }}`
+
+- `push` — appends a value to an array in place (mutates the original):
+  - Nunjucks: `{{ items | push("c") }}`
+  - Liquid: `{{ items | push: "c" }}`
+
+- `svg` — reads an SVG file and injects it inline. The path is resolved relative to the project root. Returns empty string if the file doesn't exist or isn't an SVG. Usage: `{{ 'src/icons/logo.svg' | svg }}`
+
+- `highlight` — syntax-highlights a code string at build time using highlight.js. Takes an optional language argument. If the language is omitted, highlight.js will auto-detect it. Returns a `<pre><code class="hljs">` block with highlighted markup.
+  - Nunjucks: `{{ someCodeVariable | highlight('javascript') }}`
+  - Liquid: `{{ someCodeVariable | highlight: 'javascript' }}`
+
+- `srcset` — returns just the srcset attribute value:
+
+```html
+<img
+  src="static/photo-640w.jpg"
+  srcset="{{ 'static/photo.jpg' | srcset }}"
+  sizes="100vw"
+  alt="Hero"
+/>
+```
+
+Returns: `static/photo-320w.webp 320w, static/photo-640w.webp 640w, static/photo-960w.webp 960w`
+
+#### 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.
+
+To enable, add `searchIndex` and/or `sitemap` to your markup config:
+
+```json
+{
+  "markup": {
     "in": "src/markup",
     "out": "dist",
     "options": {
-      "site": {
-        "title": "My Awesome Site",
-        "description": "This is my awesome site"
-      },
-      "data": [
-        "data/links.json",
-        "data/other.yaml"
-      ],
-      "includePaths": [
-        "_includes"
-      ]
+      "searchIndex": "search-index.json",
+      "sitemap": "sitemap.xml"
     }
   }
 }
 ```
 
-If your project doesn't have markups, you can remove the `markups` property from the config entirely. No code will be executed for this property.
+The string shorthand sets the output filename with default options. For more control, use the object form:
 
-#### Custom Filters
+```json
+{
+  "searchIndex": {
+    "output": "search-index.json",
+    "minWordLength": 3,
+    "maxKeywords": 20,
+    "globalFrequencyCeiling": 0.8,
+    "stopWords": "path/to/custom-stop-words.json"
+  },
+  "sitemap": {
+    "output": "sitemap.xml"
+  }
+}
+```
+
+**Search Index options:**
+
+- `output` — output filename, written to the markup output directory
+- `minWordLength` — minimum word length to consider as a keyword (default: `3`)
+- `maxKeywords` — maximum keywords per page (default: `20`)
+- `globalFrequencyCeiling` — drop words appearing in more than this fraction of all pages (default: `0.8`, meaning words found in 80%+ of pages are dropped as non-discriminating)
+- `stopWords` — customise stop word filtering:
+  - omit or `undefined` — uses the bundled English stop words
+  - `false` — disables stop word filtering entirely
+  - `["word1", "word2"]` — inline array of stop words
+  - `"path/to/file.json"` — path to a JSON array file (relative to project root)
+
+**Search Index output format:**
+
+All front matter fields are passed through to the index automatically. Internal fields (`content`, `isIndex`, `layout`, `published`) are stripped. If a page defines `keywords` in its front matter, those are used as-is instead of auto-extracted ones.
+
+```json
+[
+  {
+    "title": "My Post",
+    "date": "2024-01-15",
+    "description": "A great post about things.",
+    "collection": "blog",
+    "tags": ["javascript", "bundler"],
+    "url": "blog/my-post.html",
+    "keywords": ["javascript", "bundler", "webpack", "esbuild"]
+  }
+]
+```
+
+**Sitemap** generates a standard `sitemap.xml` with `<loc>` and `<lastmod>` (from front matter `date`). If `site.url` is set in your markup config, it is prepended to all URLs. Collection index/pagination pages are included in the sitemap but excluded from the search index.
 
-- `slugify` - slugifies a string. Usage: `{{ "My Awesome Title" | slugify }}` will output `my-awesome-title`
+Pages with `published: false` in their front matter are excluded from both outputs.
 
 ### Copy
 
@@ -525,15 +984,16 @@ Same as `watch` property, `includePaths` accepts an array of paths to include. I
 - [ ] 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
-  - [ ] Refactor nunjucks implementation
-  - [ ] Complete documentation for nunjucks
+  - [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
-  - [ ] Support for images and creating srcsets
+  - [x] Support for images and creating srcsets
+- [x] Add Liquid template engine as a swappable alternative to Nunjucks
 
 ## Why?