poops 1.2.4 → 1.4.0

package/README.md

@@ -24,6 +24,37 @@ Intuitive with a minimal learning curve and minimal docs, utilizing the most eff
 
 It uses a simple config file where you define your input and output paths and it poops out your bundled files. Simple as that.
 
+## Table of Contents
+
+- [Features](#features)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+  - [Scripts](#scripts)
+    - [JSX/TSX (React) Example](#jsxtsx-react-example)
+  - [Reactor (React Pre-rendering)](#reactor-react-pre-rendering)
+  - [Styles](#styles)
+    - [Design Tokens](#design-tokens)
+  - [PostCSS (optional)](#postcss-optional)
+    - [Tailwind CSS Example](#tailwind-css-example)
+  - [Markups](#markups)
+    - [Nunjucks vs Liquid](#nunjucks-vs-liquid)
+    - [Custom Engines](#custom-engines)
+    - [Collections & Pagination](#collections--pagination)
+    - [Custom Tags](#custom-tags)
+      - [image](#image)
+      - [googleFonts](#googlefonts)
+      - [highlight](#highlight)
+    - [Custom Filters](#custom-filters)
+    - [Search Index, Sitemap & Navigation](#search-index-sitemap--navigation)
+  - [Images (optional)](#images-optional)
+  - [Copy](#copy)
+  - [Banner (optional)](#banner-optional)
+  - [Local Server (optional)](#local-server-optional)
+  - [Live Reload (optional)](#live-reload-optional)
+  - [Watch (optional)](#watch-optional)
+  - [Include Paths (optional)](#include-paths-optional)
+- [Why?](#why)
+
 ## Features
 
 - Bundles SCSS/SASS to CSS
@@ -174,8 +205,8 @@ You can freely remove the properties that you don't need. For example, if you do
 
 Scripts are bundled with [esbuild](https://esbuild.github.io/). Supports `.js`, `.ts`, `.jsx`, and `.tsx` files out of the box — including React and other JSX frameworks. You can specify multiple scripts to bundle. Each script has the following properties:
 
-- `in` - the input path, can be an array of file paths, but please just use one file path per script
-- `out` - the output path, can be a directory or a file path, but please just use it as a filename
+- `in` - the input path, can be a file path, an array of file paths, or a glob pattern (e.g. `"src/js/*.js"`). Globs must use `/` separators (even on Windows)
+- `out` - the output path, can be a directory or a file path. With multiple inputs it must be a directory — entry points from different directories nest their output under the common ancestor (esbuild's `outbase`)
 - `options` - the options for the bundler. You can apply most of the esbuild options that are not in conflict with Poops. See [esbuild's options](https://esbuild.github.io/api/#build-api) for more info.
 
 **Options:**
@@ -308,8 +339,8 @@ Poops does not need `react` or `react-dom` as its own dependency — they are re
 
 Styles are bundled with [Dart Sass](https://sass-lang.com/dart-sass). You can specify multiple styles to bundle. Each style has the following properties:
 
-- `in` - the input path, accepts only a path to a file
-- `out` - the output path, can be a directory or a file path, but please just use it as a filename
+- `in` - the input path, can be a file path, an array of file paths, or a glob pattern (e.g. `"src/scss/*.scss"`). Globs must use `/` separators (even on Windows) and skip Sass partials (`_*.scss`). Each matched file is compiled separately
+- `out` - the output path, can be a directory or a file path. With multiple inputs it must be a directory — each input compiles to `<out>/<basename>.css`, so inputs sharing a basename (e.g. `a/main.scss` and `b/main.scss`) will overwrite each other
 - `options` - the options for the bundler.
 
 **Options:**
@@ -465,37 +496,34 @@ You can also pass options to plugins using the tuple form:
 
 #### Tailwind CSS Example
 
-The `example-tailwind/` directory demonstrates using Tailwind CSS v4 with Poops. To run it:
+Install the deps, then use a config like this:
 
 ```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",
+    "in": "src/css/main.css",
+    "out": "dist/css/main.css",
     "options": {
       "plugins": ["@tailwindcss/postcss"],
       "minify": true
     }
   },
   "markup": {
-    "in": "example-tailwind/src/markup",
-    "out": "example-tailwind/dist",
+    "in": "src/markup",
+    "out": "dist",
     "site": {
       "title": "Poops + Tailwind",
       "description": "A Tailwind CSS example for Poops"
     },
     "includePaths": ["_layouts", "_partials"]
   },
-  "serve": { "port": 4041, "base": "/example-tailwind/dist" },
+  "serve": { "port": 4040, "base": "/dist" },
   "livereload": true,
-  "watch": ["example-tailwind/src"]
+  "watch": ["src"]
 }
 ```
 
@@ -511,7 +539,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.
@@ -561,7 +589,7 @@ 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                                |
 | -------------- | ----------------------------- | ------------------------------------- |
@@ -574,6 +602,62 @@ Both engines support the same feature set (collections, pagination, search index
 
 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.
@@ -659,6 +743,12 @@ From the example site's `changelog/index.html`:
 {% 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
@@ -806,7 +896,7 @@ All filters are available in both engines. The only syntax difference is how arg
 
 - `jsonify` — serializes a value to JSON. Usage: `{{ myObject | jsonify }}`
 
-- `markdown` — renders a markdown string to HTML. Usage: `{{ "**bold**" | markdown }}`
+- `markdown` — renders a markdown string to HTML with GitHub-style emoji shortcodes (e.g. `:rocket:` → 🚀). Usage: `{{ "**bold** :rocket:" | 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") }}`
@@ -918,11 +1008,11 @@ Returns: `static/photo-320w.webp 320w, static/photo-640w.webp 640w, static/photo
   {% endfor %}
   ```
 
-#### Search Index & Sitemap
+#### Search Index, Sitemap & Navigation
 
-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.
+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` and/or `sitemap` to your markup config:
+To enable, add `searchIndex`, `sitemap` and/or `nav` to your markup config:
 
 ```json
 {
@@ -988,6 +1078,116 @@ 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).

package/lib/copy.js

@@ -95,7 +95,7 @@ export default class Copy {
     // 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)) {

package/lib/markup/collections.js

@@ -3,12 +3,12 @@ import { globSync } from 'glob'
 import path from 'node:path'
 import log from '../utils/log.js'
 import { mkDir, toPosix } from '../utils/helpers.js'
-import { replaceOutExtensions, getRelativePathPrefix, getPageUrl, parseFrontMatter, wordcount } from './helpers.js'
+import { replaceOutExtensions, getRelativePathPrefix, getPageUrlRelativeToOutput, parseFrontMatter, wordcount } from './helpers.js'
 
 export function getSingleCollectionData(markupInDir, collectionName) {
   const collectionData = []
   // 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) => {
+  globSync(toPosix(path.resolve(process.cwd(), markupInDir, collectionName, '**/*.+(html|njk|liquid|md)')), { ignore: ['**/index.+(html|njk|liquid|md)'] }).forEach((file) => {
     let frontMatter = {}
 
     let content = ''
@@ -47,7 +47,7 @@ export function getSingleCollectionData(markupInDir, collectionName) {
 }
 
 export function collectionAutoDiscovery(markupInDir) {
-  const indexFiles = globSync(toPosix(path.join(process.cwd(), markupInDir, '/**/index.+(html|njk|liquid|md)')))
+  const indexFiles = globSync(toPosix(path.resolve(process.cwd(), markupInDir, '**/index.+(html|njk|liquid|md)')))
 
   const collectionData = {}
 
@@ -184,13 +184,13 @@ export function buildCollectionPaginationData(collectionData) {
 }
 
 export function getCollectionIndexFile(markupInDir, collectionName) {
-  const indexFiles = globSync(toPosix(path.join(process.cwd(), markupInDir, collectionName, 'index.+(html|njk|liquid|md)')))
+  const indexFiles = globSync(toPosix(path.resolve(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)
+  const outDir = path.resolve(process.cwd(), markupOutDir, collectionName)
   if (!fs.existsSync(outDir)) return
 
   for (const entry of fs.readdirSync(outDir)) {
@@ -198,7 +198,7 @@ export function pruneStalePaginationDirs(collectionName, markupInDir, markupOutD
     // 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
+    if (fs.existsSync(path.resolve(process.cwd(), markupInDir, collectionName, entry))) continue
     fs.rmSync(path.join(outDir, entry), { recursive: true, force: true })
   }
 }
@@ -245,15 +245,16 @@ export function generateCollectionPaginationPages(collectionData, markupInDir, m
         prevPageUrl
       }
 
-      const markupOut = path.join(process.cwd(), markupOutDir, pageUrl, 'index.html')
-      const fromPath = path.join(process.cwd(), markupOutDir)
+      const markupOut = path.resolve(process.cwd(), markupOutDir, pageUrl, 'index.html')
+      const fromPath = path.resolve(process.cwd(), markupOutDir)
       const markupOutDirFull = path.dirname(markupOut)
 
       const context = {
         ...collectionData,
         [collectionName]: pageSnapshot,
         relativePathPrefix: getRelativePathPrefix(markupOutDirFull, fromPath, baseURL),
-        _url: getPageUrl(markupOut)
+        // output-relative so page.url matches nav.json/index urls, same as compileDirectory
+        _url: getPageUrlRelativeToOutput(markupOut, markupOutDir)
       }
 
       // mkDir only when a page is actually written: no empty pagination dirs

package/lib/markup/engines/liquid.js

@@ -1,20 +1,18 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { Liquid } from 'liquidjs'
-import { Marked } from 'marked'
-import { highlightRenderer, highlightCode } from '../highlight.js'
-import { discoverImageVariants, parseFrontMatter, groupby, decodeTemplateEntities, buildImageTag } from '../helpers.js'
+import { highlightCode } from '../highlight.js'
+import { marked, renderMarkdown } from '../renderer.js'
+import { discoverImageVariants, parseFrontMatter, groupby, buildImageTag, buildPaginationTag, renderToc } from '../helpers.js'
 import { getImageExif, listImages } from '../image-cache.js'
 import { slugify } from 'book-of-spells'
 import dayjs from 'dayjs'
 
-const marked = new Marked({ renderer: highlightRenderer })
-
 export default class LiquidEngine {
   constructor(templatesDir, includePaths) {
     const roots = [templatesDir]
     for (const inc of includePaths || []) {
-      roots.push(path.join(templatesDir, inc))
+      roots.push(path.resolve(templatesDir, inc))
     }
     // Also add any _* directories as include roots
     try {
@@ -48,6 +46,7 @@ export default class LiquidEngine {
     engine.registerFilter('slugify', (str) => slugify(str))
     engine.registerFilter('jsonify', (obj) => JSON.stringify(obj))
     engine.registerFilter('markdown', (str) => marked.parse(str))
+    engine.registerFilter('toc', (html) => renderToc(String(html || '')))
     engine.registerFilter('date', (str, template) => {
       const fmt = template || timeDateFormat
       if (!fmt) return str
@@ -71,17 +70,17 @@ export default class LiquidEngine {
       return content
     })
     engine.registerFilter('srcset', (imagePath) => {
-      const outputDir = path.join(process.cwd(), markupOut)
+      const outputDir = path.resolve(process.cwd(), markupOut)
       const { variants } = discoverImageVariants(imagePath, outputDir)
       if (variants.length === 0) return ''
       return variants.map(v => `${v.path} ${v.width}w`).join(', ')
     })
     engine.registerFilter('exif', (imagePath) => {
-      const outputDir = path.join(process.cwd(), markupOut)
+      const outputDir = path.resolve(process.cwd(), markupOut)
       return getImageExif(imagePath, outputDir)
     })
     engine.registerFilter('images', (dirPath) => {
-      const outputDir = path.join(process.cwd(), markupOut)
+      const outputDir = path.resolve(process.cwd(), markupOut)
       return listImages(dirPath, outputDir)
     })
     engine.registerFilter('groupby', (arr, key, datePart) => groupby(arr, key, datePart))
@@ -95,6 +94,7 @@ export default class LiquidEngine {
   registerTags(getOutputDir) {
     registerGoogleFontsTag(this.engine)
     registerImageTag(this.engine, getOutputDir)
+    registerPaginationTag(this.engine)
     registerHighlightTag(this.engine)
   }
 
@@ -112,7 +112,7 @@ export default class LiquidEngine {
     source = frontMatterResult.content
 
     if (path.extname(templateName) === '.md') {
-      source = decodeTemplateEntities(marked.parse(source))
+      source = renderMarkdown(source)
     }
 
     const frontMatter = context.page || {}
@@ -207,6 +207,19 @@ function registerImageTag(engine, getOutputDir) {
   })
 }
 
+function registerPaginationTag(engine) {
+  engine.registerTag('pagination', {
+    parse(tagToken) {
+      this.value = tagToken.args.trim()
+    },
+    * render(ctx) {
+      const pagination = yield this.liquid.evalValue(this.value, ctx)
+      const prefix = (yield ctx.get(['relativePathPrefix'])) || ''
+      return buildPaginationTag(pagination, prefix)
+    }
+  })
+}
+
 function registerHighlightTag(engine) {
   engine.registerTag('highlight', {
     parse(tagToken, remainTokens) {

package/lib/markup/engines/nunjucks.js

@@ -1,18 +1,16 @@
 import fs from 'node:fs'
 import { globSync } from 'glob'
-import { Marked } from 'marked'
 import nunjucks from 'nunjucks'
 import path from 'node:path'
-import { discoverImageVariants, parseFrontMatter, groupby, decodeTemplateEntities, buildImageTag } from '../helpers.js'
+import { discoverImageVariants, parseFrontMatter, groupby, buildImageTag, buildPaginationTag, renderToc } from '../helpers.js'
 import { getImageExif, listImages } from '../image-cache.js'
 import { toPosix } from '../../utils/helpers.js'
-import { highlightRenderer, highlightCode } from '../highlight.js'
+import { highlightCode } from '../highlight.js'
+import { marked, renderMarkdown } from '../renderer.js'
 import { slugify } from 'book-of-spells'
 import dayjs from 'dayjs'
 import log from '../../utils/log.js'
 
-const marked = new Marked({ renderer: highlightRenderer })
-
 class RelativeLoader extends nunjucks.Loader {
   constructor(templatesDir, includePaths) {
     super()
@@ -48,7 +46,7 @@ class RelativeLoader extends nunjucks.Loader {
     }
 
     if (path.extname(fullPath) === '.md') {
-      source = decodeTemplateEntities(marked.parse(source))
+      source = renderMarkdown(source)
     }
 
     if (frontMatter.layout) {
@@ -82,6 +80,12 @@ export default class NunjucksEngine {
     env.addFilter('slugify', slugify)
     env.addFilter('jsonify', (obj) => JSON.stringify(obj))
     env.addFilter('markdown', (str) => marked.parse(str))
+    env.addFilter('toc', (html) => {
+      const toc = renderToc(String(html || ''))
+      // plain '' (falsy) when there are no headings, so `{% if x | toc %}` can
+      // skip an empty TOC column; SafeString otherwise to keep the markup raw
+      return toc ? new nunjucks.runtime.SafeString(toc) : ''
+    })
     env.addFilter('concat', (arr, value) => {
       if (!Array.isArray(arr)) return [value]
       return arr.concat(value)
@@ -105,17 +109,17 @@ export default class NunjucksEngine {
       return dayjs(date).format(fmt)
     })
     env.addFilter('srcset', (imagePath) => {
-      const outputDir = path.join(process.cwd(), markupOut)
+      const outputDir = path.resolve(process.cwd(), markupOut)
       const { variants } = discoverImageVariants(imagePath, outputDir)
       if (variants.length === 0) return ''
       return variants.map(v => `${v.path} ${v.width}w`).join(', ')
     })
     env.addFilter('exif', (imagePath) => {
-      const outputDir = path.join(process.cwd(), markupOut)
+      const outputDir = path.resolve(process.cwd(), markupOut)
       return getImageExif(imagePath, outputDir)
     })
     env.addFilter('images', (dirPath) => {
-      const outputDir = path.join(process.cwd(), markupOut)
+      const outputDir = path.resolve(process.cwd(), markupOut)
       return listImages(dirPath, outputDir)
     })
     env.addFilter('groupby', (arr, key, datePart) => groupby(arr, key, datePart))
@@ -129,6 +133,7 @@ export default class NunjucksEngine {
   registerTags(getOutputDir) {
     this.env.addExtension('GoogleFontsExtension', new GoogleFontsExtension())
     this.env.addExtension('ImageExtension', new ImageExtension(getOutputDir))
+    this.env.addExtension('PaginationExtension', new PaginationExtension())
     this.env.addExtension('HighlightExtension', new HighlightExtension())
   }
 
@@ -247,3 +252,19 @@ export class HighlightExtension {
     )
   }
 }
+
+export class PaginationExtension {
+  constructor() { this.tags = ['pagination'] }
+
+  parse(parser, nodes) {
+    const tok = parser.nextToken()
+    const args = parser.parseSignature(null, true)
+    parser.advanceAfterBlockEnd(tok.value)
+    return new nodes.CallExtension(this, 'run', args)
+  }
+
+  run(context, pagination) {
+    const prefix = context.lookup('relativePathPrefix') || ''
+    return new nunjucks.runtime.SafeString(buildPaginationTag(pagination, prefix))
+  }
+}

package/lib/markup/helpers.js

@@ -83,6 +83,25 @@ export function decodeTemplateEntities(html) {
   )
 }
 
+// Builds a flat H2/H3 table of contents from rendered HTML, reading the ids
+// the markdown heading renderer emits so TOC links always match the anchors.
+// H3s carry a `toc-h3` class for indentation — no nested <ul>, so leading H3s
+// (no parent H2) stay valid. Heading text is already entity-encoded by marked,
+// so it's spliced in as-is (re-escaping would double-encode &amp;).
+export function renderToc(html) {
+  if (!html) return ''
+  const re = /<h([23])\b[^>]*\sid="([^"]*)"[^>]*>([\s\S]*?)<\/h\1>/gi
+  let items = ''
+  let match
+  while ((match = re.exec(html)) !== null) {
+    const text = match[3].replace(/<[^>]*>/g, '').trim()
+    if (!match[2] || !text) continue
+    items += `<li class="toc-h${match[1]}"><a href="#${match[2]}">${text}</a></li>`
+  }
+  if (!items) return ''
+  return `<nav class="toc" aria-label="On this page"><ul>${items}</ul></nav>`
+}
+
 export function groupby(arr, key, datePart) {
   if (!Array.isArray(arr)) return []
 
@@ -280,6 +299,18 @@ export function escapeAttr(value) {
   return String(value).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
 }
 
+export function buildPaginationTag(pagination, prefix = '') {
+  const totalPages = Number(pagination && pagination.totalPages) || 1
+  if (totalPages <= 1) return ''
+
+  const pageNumber = Number(pagination && pagination.pageNumber) || 1
+  const parts = []
+  if (pagination.prevPageUrl) parts.push(`<a href="${escapeAttr(prefix + pagination.prevPageUrl)}">Previous</a>`)
+  parts.push(`<span>${pageNumber} of ${totalPages}</span>`)
+  if (pagination.nextPageUrl) parts.push(`<a href="${escapeAttr(prefix + pagination.nextPageUrl)}">Next</a>`)
+  return parts.join('\n')
+}
+
 // Shared by the nunjucks and liquid `image` tags — attribute values may come
 // from front-matter/user data, so they are escaped here, once for both engines.
 export function buildImageTag(imagePath, prefix, kwargs, getOutputDir) {