poops 1.2.4 → 1.3.0

package/README.md

@@ -511,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.
@@ -561,7 +561,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 +574,52 @@ 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 +705,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
@@ -918,11 +970,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 +1040,105 @@ 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) {

package/lib/markup/indexer.js

@@ -152,7 +152,159 @@ export function generateSitemap(pageEntries, outputDir, siteUrl, config) {
   log({ tag: 'indexer', text: 'Generated sitemap:', link: path.relative(process.cwd(), outputPath), size: fileSize(outputPath) })
 }
 
+function humanizeSegment(seg) {
+  return seg
+    .replace(/[-_]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/\b\w/g, c => c.toUpperCase())
+}
+
+function navNodeTitle(entry) {
+  return entry.navTitle || entry.title
+}
+
+// Applies the `collections` option (true | false | ["name"] | "index") on top
+// of the base exclusions (nav:false, and isIndex pages which are collection
+// landing/pagination). "index" is the exception that re-admits each
+// collection's first landing page as a single leaf.
+function navFilterEntries(pageEntries, collectionsOpt) {
+  const mode = collectionsOpt === undefined ? true : collectionsOpt
+  const allowlist = Array.isArray(mode) ? new Set(mode) : null
+  const result = []
+
+  for (const e of pageEntries) {
+    if (e.nav === false) continue
+
+    if (e.isIndex) {
+      // collection landing (url === name, no slash) kept only in "index" mode;
+      // pagination pages (url has a slash) always dropped. Landing titles are
+      // the raw collection name ("blog"), so humanize for display.
+      if (mode === 'index' && !e.url.includes('/')) {
+        result.push({ ...e, title: humanizeSegment(e.title) })
+      }
+      continue
+    }
+
+    if (e.collection != null) {
+      if (mode === false || mode === 'index') continue
+      if (allowlist && !allowlist.has(e.collection)) continue
+    }
+    result.push(e)
+  }
+
+  return result
+}
+
+function insertNavNode(root, entry) {
+  let cursor = root
+  for (const seg of entry.url.split('/')) {
+    if (!cursor.children.has(seg)) {
+      cursor.children.set(seg, { segment: seg, children: new Map() })
+    }
+    cursor = cursor.children.get(seg)
+  }
+  cursor.hasPage = true
+  cursor.url = entry.url
+  cursor.title = navNodeTitle(entry)
+  if (entry.order != null) cursor.order = entry.order
+}
+
+function getNavNode(root, urlPath) {
+  let cursor = root
+  for (const seg of urlPath.split('/')) {
+    cursor = cursor.children.get(seg)
+    if (!cursor) return null
+  }
+  return cursor
+}
+
+function sortNavSiblings(nodes) {
+  nodes.sort((a, b) => {
+    const oa = a.order != null ? a.order : Infinity
+    const ob = b.order != null ? b.order : Infinity
+    if (oa !== ob) return oa - ob
+    return String(a.title).localeCompare(String(b.title))
+  })
+}
+
+// Post-order: children are serialized (and thus order-resolved) before the
+// parent, so a virtual parent can borrow its first child's order.
+function serializeNavNode(node) {
+  const children = [...node.children.values()].map(serializeNavNode)
+  sortNavSiblings(children)
+
+  const out = { title: node.title != null ? node.title : humanizeSegment(node.segment) }
+  if (node.url != null) out.url = node.url
+
+  let order = node.order
+  if (order == null && !node.hasPage && children.length) order = children[0].order
+  if (order != null) out.order = order
+
+  if (children.length) out.children = children
+  return out
+}
+
+export function buildNavTree(pageEntries, config = {}) {
+  const { collections, home, root } = config
+  let entries = navFilterEntries(pageEntries, collections)
+
+  if (root != null) {
+    const prefix = root + '/'
+    entries = entries.filter(e => e.url === root || e.url.startsWith(prefix))
+  } else if (home === false) {
+    entries = entries.filter(e => e.url !== '')
+  }
+
+  const tree = { children: new Map() }
+  let homeEntry = null
+  for (const entry of entries) {
+    // root index page (url '') can't be segment-split — it would corrupt the
+    // tree; handle it as a top-level leaf instead
+    if (entry.url === '') { homeEntry = entry; continue }
+    insertNavNode(tree, entry)
+  }
+
+  // root scoping: emit the section's children unwrapped to the top level, with
+  // the section's own index page (if any) pinned first as the overview link
+  if (root != null) {
+    const rootNode = getNavNode(tree, root)
+    if (!rootNode) return []
+    const top = [...rootNode.children.values()].map(serializeNavNode)
+    sortNavSiblings(top)
+    if (rootNode.hasPage) {
+      const overview = { title: rootNode.title, url: rootNode.url }
+      if (rootNode.order != null) overview.order = rootNode.order
+      top.unshift(overview)
+    }
+    return top
+  }
+
+  const top = [...tree.children.values()].map(serializeNavNode)
+  if (homeEntry) {
+    const node = { title: navNodeTitle(homeEntry), url: '' }
+    if (homeEntry.order != null) node.order = homeEntry.order
+    top.push(node)
+  }
+  sortNavSiblings(top)
+  return top
+}
+
+export function generateNav(pageEntries, outputDir, config) {
+  config = normalizeConfig(config)
+  if (!config) return
+
+  const tree = buildNavTree(pageEntries, config)
+
+  // resolve, not join: outputDir may be absolute (join would mangle it,
+  // e.g. cross-drive temp dirs on Windows)
+  const outputPath = path.resolve(process.cwd(), outputDir, config.output)
+  fs.writeFileSync(outputPath, JSON.stringify(tree, null, 2))
+  log({ tag: 'indexer', text: 'Generated nav:', link: path.relative(process.cwd(), outputPath), size: fileSize(outputPath) })
+}
+
 export function generateIndexFiles(pageEntries, outputDir, siteUrl, config) {
   generateSearchIndex(pageEntries, outputDir, config.searchIndex)
   generateSitemap(pageEntries, outputDir, siteUrl, config.sitemap)
+  generateNav(pageEntries, outputDir, config.nav)
 }

package/lib/markup/renderer.js

@@ -0,0 +1,60 @@
+import { Marked } from 'marked'
+import { slugify } from 'book-of-spells'
+import { highlightRenderer, highlightCode } from './highlight.js'
+import { decodeTemplateEntities } from './helpers.js'
+
+const RAW_BLOCK_RE = /\{%-?\s*raw\s*-?%\}([\s\S]*?)\{%-?\s*endraw\s*-?%\}/g
+
+// Applies `outside` to the text between {% raw %} blocks and `inside` to each
+// block's inner content, re-emitting the delimiters untouched so the template
+// engine still sees them. The two places that would otherwise mangle raw
+// content route through this: fence highlighting and entity decoding.
+function mapRawSegments(str, outside, inside) {
+  RAW_BLOCK_RE.lastIndex = 0
+  let out = ''
+  let last = 0
+  for (const m of str.matchAll(RAW_BLOCK_RE)) {
+    out += outside(str.slice(last, m.index))
+    out += `{% raw %}${inside(m[1])}{% endraw %}`
+    last = m.index + m[0].length
+  }
+  return out + outside(str.slice(last))
+}
+
+// The marked renderer used across the markup engines: syntax highlighting
+// (from highlight.js) plus heading slug ids + permalink anchors.
+export const markdownRenderer = {
+  ...highlightRenderer,
+  // Fenced code goes through hljs, which wraps `{`/`%` in their own spans —
+  // splitting a {% raw %} tag so the template engine never sees it and
+  // evaluates the "raw" content (e.g. a {{ name }} in a config sample rendered
+  // as empty). Highlight around/inside each raw block instead, keeping the
+  // fence's language, and pass the delimiters through intact. Inline code
+  // never splits the delimiters, so it needs no special casing.
+  code(code, lang) {
+    const highlighted = mapRawSegments(code, (s) => s && highlightCode(s, lang), (s) => highlightCode(s, lang))
+    const langClass = lang ? ` language-${lang.replace(/[^\w-]/g, '')}` : ''
+    return `<pre><code class="hljs${langClass}">${highlighted}</code></pre>\n`
+  },
+  // Give every heading a slug id + a permalink anchor. The anchor is empty on
+  // purpose — themes reveal a "#" via `.heading-anchor::before`, so a site with
+  // no such CSS renders an invisible anchor instead of a stray "#".
+  // ponytail: no slug dedup — two identical headings on one page share an id;
+  // add a per-parse counter if that ever bites.
+  heading(text, level, raw) {
+    const id = slugify(raw || '')
+    if (!id) return `<h${level}>${text}</h${level}>\n`
+    return `<h${level} id="${id}">${text}<a class="heading-anchor" href="#${id}" aria-label="Permalink" aria-hidden="true"></a></h${level}>\n`
+  }
+}
+
+// One shared instance so both engines render markdown identically.
+export const marked = new Marked({ renderer: markdownRenderer })
+
+// Renders a markdown page source for the template engines. Entity decoding
+// (which un-escapes inside {{ }} / {% %} so template args parse) must skip
+// raw blocks — their content is for display, so its entities have to survive
+// to the browser.
+export function renderMarkdown(source) {
+  return mapRawSegments(marked.parse(source), decodeTemplateEntities, (s) => s)
+}

package/lib/markups.js

@@ -1,12 +1,14 @@
 import { pathExists, pathIsDirectory, readDataFile, mkDir, buildTime, toPosix } from './utils/helpers.js'
-import { replaceOutExtensions, getRelativePathPrefix, getPageUrl, getPageUrlRelativeToOutput, parseFrontMatter, clearFrontMatterCache, wordcount } from './markup/helpers.js'
+import { replaceOutExtensions, getRelativePathPrefix, getPageUrlRelativeToOutput, parseFrontMatter, clearFrontMatterCache, wordcount } from './markup/helpers.js'
 import { collectionAutoDiscovery, getCollectionDataBasedOnConfig, buildCollectionPaginationData, generateCollectionPaginationPages } from './markup/collections.js'
-import { generateIndexFiles } from './markup/indexer.js'
+import { generateIndexFiles, buildNavTree } from './markup/indexer.js'
 import NunjucksEngine from './markup/engines/nunjucks.js'
 import LiquidEngine from './markup/engines/liquid.js'
 import fs from 'node:fs'
 import { globSync } from 'glob'
 import path from 'node:path'
+import { createRequire } from 'node:module'
+import { pathToFileURL } from 'node:url'
 import log from './utils/log.js'
 
 const ENGINES = {
@@ -22,8 +24,8 @@ export default class Markups {
     if (!moduleConfig || !moduleConfig.in) return
     if (!moduleConfig.options) moduleConfig.options = {}
 
-    // Determine engine
-    const engineName = moduleConfig.engine || moduleConfig.options.engine || 'nunjucks'
+    // Determine engine — resolved in init(), builtin name or importable module
+    this.engineName = moduleConfig.engine || moduleConfig.options.engine || 'nunjucks'
     this.logTag = 'markup'
 
     // Normalize config
@@ -35,22 +37,54 @@ export default class Markups {
     this.includePaths = moduleConfig.includePaths || moduleConfig.options.includePaths || []
     this.searchIndexConfig = moduleConfig.options.searchIndex || moduleConfig.searchIndex
     this.sitemapConfig = moduleConfig.options.sitemap || moduleConfig.sitemap
+    this.navConfig = moduleConfig.options.nav || moduleConfig.nav
     this.baseURL = moduleConfig.baseURL || moduleConfig.options.baseURL || null
 
-    // Instantiate engine
-    const EngineClass = ENGINES[engineName]
+    this.autoescape = moduleConfig.autoescape || moduleConfig.options.autoescape || false
+    this.dataConfig = moduleConfig.data || moduleConfig.options.data
+
+    if (!moduleConfig.out) {
+      moduleConfig.out = this.markupOut
+    }
+  }
+
+  // Engine instantiation is async because non-builtin engines are loaded via
+  // dynamic import. Idempotent; compile() calls it lazily, so a failed engine
+  // resolution logs once per compile and the module stays inert.
+  async init() {
+    if (!this.markupIn || this.engine) return
+
+    let EngineClass = ENGINES[this.engineName]
     if (!EngineClass) {
-      log({ tag: 'error', text: `Unknown markup engine: ${engineName}` })
+      try {
+        // Relative/absolute specifiers resolve against cwd (the user's
+        // project), bare specifiers against the module graph (node_modules)
+        const spec = /^[./]/.test(this.engineName) || path.isAbsolute(this.engineName)
+          ? pathToFileURL(path.resolve(process.cwd(), this.engineName)).href
+          : this.engineName
+        EngineClass = (await import(spec)).default
+      } catch {
+        // Bare specifier not reachable from poops's own module graph (e.g.
+        // poops installed via a file: link) — resolve from the user's project
+        try {
+          const projectRequire = createRequire(path.join(process.cwd(), 'package.json'))
+          EngineClass = (await import(pathToFileURL(projectRequire.resolve(this.engineName)).href)).default
+        } catch { /* handled below */ }
+      }
+    }
+
+    if (typeof EngineClass !== 'function') {
+      log({ tag: 'error', text: `Unknown markup engine: ${this.engineName}` })
       return
     }
 
-    const templatesDir = path.join(process.cwd(), this.markupIn)
+    const templatesDir = path.resolve(process.cwd(), this.markupIn)
     this.engine = new EngineClass(templatesDir, this.includePaths, {
-      autoescape: moduleConfig.autoescape || moduleConfig.options.autoescape || false
+      autoescape: this.autoescape
     })
 
     this.engine.registerFilters({ timeDateFormat: this.timeDateFormat, markupOut: this.markupOut })
-    this.engine.registerTags(() => path.join(process.cwd(), this.markupOut))
+    this.engine.registerTags(() => path.resolve(process.cwd(), this.markupOut))
 
     // Load global variables
     const pkgPath = path.join(process.cwd(), 'package.json')
@@ -70,12 +104,7 @@ export default class Markups {
       }
     }
 
-    this.dataConfig = moduleConfig.data || moduleConfig.options.data
     this.loadDataFiles(this.dataConfig)
-
-    if (!moduleConfig.out) {
-      moduleConfig.out = this.markupOut
-    }
   }
 
   loadDataFiles(files) {
@@ -89,11 +118,11 @@ export default class Markups {
     const dataDir = pathIsDirectory(this.markupIn) ? this.markupIn : path.dirname(this.markupIn)
     const resolved = []
     for (const file of files) {
-      const fullPath = path.join(process.cwd(), dataDir, file)
+      const fullPath = path.resolve(process.cwd(), dataDir, file)
       if (pathIsDirectory(fullPath)) {
         const dirFiles = globSync(toPosix(path.join(fullPath, '**/*.+(json|yml|yaml)')))
         for (const f of dirFiles) {
-          resolved.push(path.relative(path.join(process.cwd(), dataDir), f))
+          resolved.push(path.relative(path.resolve(process.cwd(), dataDir), f))
         }
       } else {
         resolved.push(file)
@@ -103,7 +132,7 @@ export default class Markups {
     const loadedKeys = new Set()
     for (const dataFile of resolved) {
       try {
-        const data = readDataFile(path.join(process.cwd(), dataDir, dataFile))
+        const data = readDataFile(path.resolve(process.cwd(), dataDir, dataFile))
         const globalKeyName = path.basename(dataFile, path.extname(dataFile)).replace(/[.\-\s]/g, '_')
         this.engine.setGlobal(globalKeyName, data)
         loadedKeys.add(globalKeyName)
@@ -123,20 +152,29 @@ export default class Markups {
   }
 
   reloadDataFiles() {
-    this.loadDataFiles(this.dataConfig)
+    if (this.engine) this.loadDataFiles(this.dataConfig)
     return Promise.resolve()
   }
 
+  // Engines can override output extension mapping (e.g. a template format
+  // whose extension isn't in the default map); falls back to the shared helper
+  mapOutputPath(outputPath) {
+    if (this.engine && typeof this.engine.replaceOutExtensions === 'function') {
+      return this.engine.replaceOutExtensions(outputPath)
+    }
+    return replaceOutExtensions(outputPath)
+  }
+
   // Maps a deleted source path to its build output and removes it.
   // compile() only globs existing sources, so it can never clean up
   // after a deletion — this is the only place stale output gets removed.
   removeOutput(sourcePath) {
-    if (!this.engine) return
-    const markupIn = path.join(process.cwd(), this.markupIn)
-    const rel = path.relative(markupIn, path.join(process.cwd(), sourcePath))
+    if (!this.markupIn) return
+    const markupIn = path.resolve(process.cwd(), this.markupIn)
+    const rel = path.relative(markupIn, path.resolve(process.cwd(), sourcePath))
     if (rel.startsWith('..') || path.isAbsolute(rel)) return
 
-    const mapped = path.join(process.cwd(), this.markupOut, rel)
+    const mapped = path.resolve(process.cwd(), this.markupOut, rel)
 
     // rel === '' with a directory output would be the whole out dir —
     // never remove that, it also holds css/js from other modules
@@ -146,7 +184,7 @@ export default class Markups {
       return
     }
 
-    const outFile = replaceOutExtensions(mapped)
+    const outFile = this.mapOutputPath(mapped)
     if (fs.existsSync(outFile) && !fs.statSync(outFile).isDirectory()) {
       fs.unlinkSync(outFile)
       log({ tag: this.logTag, text: 'Removed:', link: path.relative(process.cwd(), outFile) })
@@ -203,13 +241,72 @@ export default class Markups {
     return { result, frontMatter }
   }
 
-  async compileDirectory(markupIn, collectionData, pageEntries) {
-    const markupStart = performance.now()
+  getMarkupFiles(markupIn) {
     // glob patterns must use `/` — on Windows `\` is an escape character
-    const markupFiles = [
+    return [
       ...globSync(toPosix(path.join(markupIn, this.generateMarkupGlobPattern(this.includePaths)))),
       ...globSync(toPosix(path.join(markupIn, `*.+(${this.engine.markupExtensions})`)))
     ]
+  }
+
+  // True for collection index templates that compileDirectory skips —
+  // pagination renders them instead
+  isCollectionIndexOverride(relativePathParts, collectionData) {
+    return relativePathParts.length > 1 &&
+      collectionData[relativePathParts[0]] &&
+      relativePathParts[1].startsWith('index.') &&
+      this.engine.indexableExtensions.has(path.extname(relativePathParts[1])) &&
+      collectionData[relativePathParts[0]].items.length > 0
+  }
+
+  // Pre-pass: builds the nav tree from front matter alone (no rendering) and
+  // exposes it as the `nav` template global, so sidebars can render during the
+  // same compile instead of reading the previous build's nav.json.
+  // parseFrontMatter caches by mtime, so the compile pass re-reads nothing.
+  buildNavGlobal(markupIn, collectionData) {
+    if (!this.navConfig) return
+
+    const entries = []
+    for (const collectionName of Object.keys(collectionData)) {
+      entries.push({ url: collectionName, title: collectionName, isIndex: true })
+    }
+
+    const files = pathIsDirectory(markupIn) ? this.getMarkupFiles(markupIn) : [markupIn]
+    for (const file of files) {
+      if (!this.engine.indexableExtensions.has(path.extname(file))) continue
+      const relativePath = path.relative(markupIn, file)
+      const relativePathParts = relativePath.split(path.sep)
+      if (this.isCollectionIndexOverride(relativePathParts, collectionData)) continue
+
+      let frontMatter
+      try {
+        frontMatter = parseFrontMatter(file).frontMatter
+      } catch (err) {
+        continue
+      }
+      if (frontMatter.published === false) continue
+      if (!frontMatter.title) frontMatter.title = path.basename(file, path.extname(file))
+
+      const fileCollection = relativePathParts.length > 1 && collectionData[relativePathParts[0]]
+        ? relativePathParts[0]
+        : null
+      if (fileCollection && !frontMatter.collection) frontMatter.collection = fileCollection
+
+      const outPath = this.mapOutputPath(path.resolve(process.cwd(), this.markupOut, relativePath))
+      entries.push({
+        ...frontMatter,
+        url: getPageUrlRelativeToOutput(outPath, this.markupOut),
+        isIndex: false
+      })
+    }
+
+    const navOptions = typeof this.navConfig === 'object' ? this.navConfig : {}
+    this.engine.setGlobal('nav', buildNavTree(entries, navOptions))
+  }
+
+  async compileDirectory(markupIn, collectionData, pageEntries) {
+    const markupStart = performance.now()
+    const markupFiles = this.getMarkupFiles(markupIn)
     const compilePromises = []
     const indexableExtensions = this.engine.indexableExtensions
 
@@ -217,15 +314,14 @@ export default class Markups {
       const relativePath = path.relative(markupIn, file)
       const relativePathParts = relativePath.split(path.sep)
 
-      if (relativePathParts.length > 1 &&
-        collectionData[relativePathParts[0]] &&
-        relativePathParts[1].startsWith('index.') && indexableExtensions.has(path.extname(relativePathParts[1])) &&
-        collectionData[relativePathParts[0]].items.length > 0) {
+      if (this.isCollectionIndexOverride(relativePathParts, collectionData)) {
         continue
       }
 
-      let markupOut = path.join(process.cwd(), this.markupOut, relativePath)
-      const fromPath = path.join(process.cwd(), this.markupOut)
+      // Map before deriving dir/prefix: engines may relocate output (e.g.
+      // Shopify's templates/ flattening), and links must match the final path.
+      const markupOut = this.mapOutputPath(path.resolve(process.cwd(), this.markupOut, relativePath))
+      const fromPath = path.resolve(process.cwd(), this.markupOut)
       const markupOutDir = path.dirname(markupOut)
 
       mkDir(markupOutDir)
@@ -233,7 +329,9 @@ export default class Markups {
       const fileContext = {
         ...collectionData,
         relativePathPrefix: getRelativePathPrefix(markupOutDir, fromPath, this.baseURL),
-        _url: getPageUrl(markupOut)
+        // output-relative so page.url matches nav.json urls (getPageUrlRelativeToOutput),
+        // otherwise `item.url == page.url` sidebar/active checks never fire
+        _url: getPageUrlRelativeToOutput(markupOut, this.markupOut)
       }
 
       const shouldIndex = pageEntries && indexableExtensions.has(path.extname(file))
@@ -243,14 +341,12 @@ export default class Markups {
 
       const compilePromise = this.compileEntry(file, fileContext).then(({ result, frontMatter, skipped }) => {
         if (skipped) {
-          const outFile = replaceOutExtensions(markupOut)
-          if (fs.existsSync(outFile)) {
-            fs.unlinkSync(outFile)
-            log({ tag: this.logTag, text: 'Removed unpublished:', link: path.relative(process.cwd(), outFile) })
+          if (fs.existsSync(markupOut)) {
+            fs.unlinkSync(markupOut)
+            log({ tag: this.logTag, text: 'Removed unpublished:', link: path.relative(process.cwd(), markupOut) })
           }
           return
         }
-        markupOut = replaceOutExtensions(markupOut)
         fs.writeFileSync(markupOut, result)
 
         if (shouldIndex && frontMatter.published !== false) {
@@ -283,7 +379,7 @@ export default class Markups {
 
   async compileSingleFile(markupIn, collectionData, pageEntries) {
     const markupStart = performance.now()
-    let markupOut = path.join(process.cwd(), this.markupOut)
+    let markupOut = path.resolve(process.cwd(), this.markupOut)
     const markupOutDir = path.dirname(markupOut)
     const indexableExtensions = this.engine.indexableExtensions
     mkDir(markupOutDir)
@@ -291,14 +387,15 @@ export default class Markups {
     const fileContext = {
       ...collectionData,
       relativePathPrefix: getRelativePathPrefix(markupOutDir, null, this.baseURL),
-      _url: getPageUrl(markupOut)
+      // output-relative so page.url matches nav.json/index urls, same as compileDirectory
+      _url: getPageUrlRelativeToOutput(this.mapOutputPath(markupOut), this.markupOut)
     }
 
     const shouldIndex = pageEntries && indexableExtensions.has(path.extname(markupIn))
 
     try {
       const { result, frontMatter, skipped } = await this.compileEntry(markupIn, fileContext)
-      markupOut = replaceOutExtensions(markupOut)
+      markupOut = this.mapOutputPath(markupOut)
 
       if (skipped) {
         if (fs.existsSync(markupOut)) {
@@ -321,9 +418,9 @@ export default class Markups {
       }
 
       const markupEnd = performance.now()
-      log({ tag: this.logTag, text: 'Compiled:', link: path.relative(process.cwd(), path.join(process.cwd(), this.markupOut, path.basename(markupIn))), time: buildTime(markupStart, markupEnd) })
+      log({ tag: this.logTag, text: 'Compiled:', link: path.relative(process.cwd(), path.resolve(process.cwd(), this.markupOut, path.basename(markupIn))), time: buildTime(markupStart, markupEnd) })
     } catch (err) {
-      log({ tag: this.logTag, error: true, text: 'Failed compiling:', link: path.relative(process.cwd(), path.join(process.cwd(), this.markupOut, path.basename(markupIn))) })
+      log({ tag: this.logTag, error: true, text: 'Failed compiling:', link: path.relative(process.cwd(), path.resolve(process.cwd(), this.markupOut, path.basename(markupIn))) })
       console.error(err)
       throw err
     } finally {
@@ -335,6 +432,9 @@ export default class Markups {
     const moduleConfig = this.config.markup
     if (!moduleConfig || !moduleConfig.in) return
 
+    await this.init()
+    if (!this.engine) return
+
     if (this.config.reactorData) {
       // A removed reactor component must also drop its injected global,
       // same staleness rule as data files in loadDataFiles()
@@ -351,7 +451,7 @@ export default class Markups {
       }
     }
 
-    const markupIn = path.join(process.cwd(), this.markupIn)
+    const markupIn = path.resolve(process.cwd(), this.markupIn)
 
     if (!pathExists(markupIn)) {
       log({ tag: 'error', text: 'Markup path does not exist:', link: markupIn })
@@ -363,10 +463,15 @@ export default class Markups {
       ...getCollectionDataBasedOnConfig(this.markupIn, this.collectionsConfig)
     }
 
-    const shouldIndex = this.searchIndexConfig || this.sitemapConfig
+    const shouldIndex = this.searchIndexConfig || this.sitemapConfig || this.navConfig
     const pageEntries = shouldIndex ? [] : null
 
     buildCollectionPaginationData(collectionData)
+
+    // must precede any rendering (incl. pagination pages) so every template
+    // sees the current build's nav
+    this.buildNavGlobal(markupIn, collectionData)
+
     const collectionPromises = generateCollectionPaginationPages(collectionData, this.markupIn, this.markupOut, this.compileEntry.bind(this), this.baseURL)
 
     await Promise.all(collectionPromises)
@@ -396,7 +501,8 @@ export default class Markups {
     if (shouldIndex && pageEntries) {
       generateIndexFiles(pageEntries, this.markupOut, this.siteData.url, {
         searchIndex: this.searchIndexConfig,
-        sitemap: this.sitemapConfig
+        sitemap: this.sitemapConfig,
+        nav: this.navConfig
       })
     }
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "poops",
   "description": "Straightforward, no-bullshit bundler for the web.",
-  "version": "1.2.4",
+  "version": "1.3.0",
   "license": "MIT",
   "type": "module",
   "main": "poops.js",

package/poops.js

@@ -3,7 +3,7 @@
 import chokidar from 'chokidar'
 import connect from 'connect'
 import Copy from './lib/copy.js'
-import { pathExists, doesFileBelongToPath } from './lib/utils/helpers.js'
+import { pathExists, doesFileBelongToPath, pathContainsPathSegment } from './lib/utils/helpers.js'
 import http from 'node:http'
 import os from 'node:os'
 import fs from 'node:fs'
@@ -85,8 +85,6 @@ function setupLiveReloadServer(config) {
 function setupWatchers(config, modules) {
   if (!config.watch) return
 
-  // TODO: think about watching the updates of the config file itself, we can reload the config and recompile everything.
-  // TODO: ability to automatically create a watch list of directories if watch is set to true. The list will be generated from the `in` property of each task.
   // awaitWriteFinish: wait for saves to finish writing before recompiling, so a
   // mid-write (truncated/partial) file is never read. Fixes intermittent broken
   // builds on editor save. Bump thresholds if slow disks flake.
@@ -95,8 +93,19 @@ function setupWatchers(config, modules) {
   // rebuilds. 'add' also covers genuinely new files (e.g. a new markup page).
   // Rebuild branches shared by change/add/deletion: a deletion needs the same
   // rebuilds (a deleted-but-still-imported file must surface the error).
+  // Scripts/styles outputs can land inside a watched dir (e.g. a Shopify
+  // theme's assets/): the compiler's own write must not retrigger that
+  // compiler, or watch loops forever. Zones are the dirs the compilers write
+  // into; only their own extensions are skipped there, so e.g. a hand-edited
+  // .liquid asset in the same dir still rebuilds markup.
+  const outputZones = [config.scripts, config.styles].flat()
+    .filter((entry) => entry && entry.out)
+    .map((entry) => (path.extname(entry.out) ? path.dirname(entry.out) : entry.out))
+    .filter((zone) => zone && zone !== '.')
+  const isBuildOutput = (file) => outputZones.some((zone) => pathContainsPathSegment(file, zone))
+
   const rebuild = (file) => {
-    if (/(\.m?jsx?|\.tsx?)$/i.test(file)) {
+    if (/(\.m?jsx?|\.tsx?)$/i.test(file) && !isBuildOutput(file)) {
       modules.scripts.compile().catch(err => console.error(err))
 
       if (modules.reactor.belongsToReactor(file)) {
@@ -108,7 +117,7 @@ function setupWatchers(config, modules) {
         }).catch(err => console.error(err))
       }
     }
-    if (/(\.sass|\.scss|\.css)$/i.test(file)) {
+    if (/(\.sass|\.scss|\.css)$/i.test(file) && !isBuildOutput(file)) {
       modules.styles.compile().then(() => modules.postcss.compile()).catch(err => console.error(err))
     }
     if (/(\.html|\.xml|\.rss|\.atom|\.njk|\.liquid|\.md)$/i.test(file)) {