@kenjura/ursa 0.93.0 → 0.95.0

package/CHANGELOG.md

@@ -1,3 +1,35 @@
+# 0.95.0
+2026-09-06
+
+`generate --json-only` builds the data and skips the site.
+
+ursa emits a `.json` beside every document and a `<dir>.json` record list beside every directory, and those files are useful on their own — an application can ingest a docs repo at build time and never serve the HTML. Getting them, though, meant paying for the whole site: rendering every page, resizing every image, bundling the React runtime, and writing a full-text index nobody would query. On the system8 docs that is 2.85s and 88 MB to obtain 8.8 MB of JSON.
+
+- **`--json-only` (`-j`) emits only the data files.** Skipped: HTML, XML, images and their previews, meta/template assets, the React runtime, per-folder CSS/JS bundles, static file copying (fonts, audio, video, PDFs), the search and full-text indices, `menu-data.json`, `recent-activity.json`, and auto-generated index pages. On the system8 docs: **1.12s and 8.8 MB**, down from 2.85s and 88 MB.
+- **The JSON is byte-identical to a full build's**, not merely similar — verified across all 1,475 content files of the system8 docs, and asserted in the test suite. Every step the mode skips operates on the assembled *page*: `bodyHtml` in the JSON is the pre-template render, and `transformImageTags`, `markInactiveLinks` and `resolveRelativeUrls` only ever rewrote the finished HTML. So there is nothing for image processing or template bundling to contribute to it.
+- **The directory record lists are kept.** They are the one thing a data consumer most wants — `character/powers.json` is the list of every power with its frontmatter — so only the directory's *listing page* is skipped, never its `.json`.
+
+Mixing modes against one source tree is safe. The `.ursa` hash cache lives in the source and is shared, so the per-document output check now asks only for the outputs the current mode emits: a JSON-only run after a full build skips work (the `.json` is present and identical either way), and a full build after a JSON-only run regenerates, because its `.html` and `.xml` are missing. That check already existed for a related reason — one hash cache serving several output directories — and it extends to modes for free.
+
+Two pieces of build state are deliberately not written by a JSON-only run. The dependency graph is skipped because registration lives inside the page assembly the mode skips, so saving would replace a full build's graph with an empty one. The watch-mode cache is skipped because it would be seeded with unbundled templates and an empty image map, which would make a later single-file regeneration emit an unstyled page.
+
+# 0.94.0
+2026-09-04
+
+`config.json { hidden: true }` now actually ignores a folder.
+
+It was documented as "hide from menu and don't generate files", and it did neither reliably. `generate` filtered articles and directories, but every other category was derived from an unfiltered list, so a hidden folder still had its images, fonts, audio and video copied into the output and its hand-written HTML carried across. Auto-index listings never consulted the setting at all, so a hidden folder was listed — with working-looking links — in its parent's index. `serve` rendered its pages on request, which is the worst version of the bug: the page works all through development and 404s in production, exactly the failure the setting exists to prevent.
+
+- **One filter, applied once.** `generate` now drops hidden paths from the whole source file list, ahead of classification, instead of re-checking in each category. Articles, directories, images, media and hand-written HTML all inherit it, so no category can be missed — which is how images and media came to be copied out of hidden folders in the first place.
+- **Auto-indices skip hidden folders**, in all three listing paths: from source, from output, and the fallback index generated for a folder without one. The output-scanning path checks the *source* tree, so a folder hidden after it was generated does not reappear from stale files left in `output/`.
+- **A folder holding nothing but a hidden subfolder is no longer treated as having content**, and so is not linked as if it had pages.
+- **`serve` returns 404 for anything under a hidden folder** — documents, images, `config.json` itself — from a single gate ahead of the static-file fallbacks. `serve` and `generate` now agree.
+- **The menu check no longer depends on the folder having children**, so an empty hidden folder is skipped too.
+
+`isFolderHidden()` accepts file paths as well as directories: the walk begins at the path itself, and a file has no `config.json` of its own, so its ancestors decide. That is what lets one predicate filter a mixed list of files and directories. Its shallow companion `isFolderSelfHidden()` tests one folder without a docroot, for the auto-index builders, which know only the folder they are listing.
+
+Files already written to `output/` before a folder was hidden are still not deleted — nothing links to them any more, but removing them needs `--clean`. That is the general "generate never deletes" behaviour, unchanged here.
+
 # 0.93.0
 2026-09-03
 

package/README.md

@@ -67,6 +67,35 @@ Start a development server that:
 - `--whitelist, -w` - Path to whitelist file containing patterns for files to include
 - `--exclude, -e` - Folders to exclude: comma-separated paths relative to source, or path to file with one folder per line
 - `--clean` - Delete the `.ursa` cache folder and clear output directory, forcing full regeneration
+- `--json-only, -j` - Emit only the `.json` data files (generate command only)
+
+### JSON-Only Builds
+
+`--json-only` builds the data and skips the site:
+
+```bash
+ursa content --json-only --output data
+```
+
+What it emits: every document's `<name>.json` and every directory's `<dir>.json`
+record list — the same files a normal build writes, byte for byte.
+
+What it skips: HTML, XML, images and their previews, meta/template assets, the
+React runtime, per-folder CSS/JS bundles, static file copying (fonts, audio,
+video, PDFs), the search and full-text indices, `menu-data.json`,
+`recent-activity.json`, and auto-generated index pages.
+
+This is for pipelines that consume ursa's JSON as data rather than publishing a
+site — ingesting a docs repo into an application at build time, for example.
+Everything skipped operates on the assembled *page*; the JSON's `bodyHtml` is
+the pre-template render, which none of those steps touch. That is why the output
+is identical rather than merely similar.
+
+Mixing modes against one source tree is safe. The two share the `.ursa` hash
+cache, but each asks only for the outputs its own mode emits, so a full build
+following a JSON-only build still writes the HTML it is missing. A JSON-only
+build does not write the dependency graph or seed the watch cache, so it cannot
+degrade a later `serve`.
 
 ### Whitelist File Format
 
@@ -124,6 +153,44 @@ old-content/v1
 test/fixtures
 ```
 
+### Ignoring a Folder
+
+To keep a folder out of the build permanently — working notes, prompt
+scratchpads, raw source material — put a `config.json` in it:
+
+```json
+{
+  "hidden": true
+}
+```
+
+The folder and everything beneath it then take no part in the build:
+
+- no HTML is rendered from its documents
+- its images, fonts and other static assets are not copied to the output
+- it does not appear in the sidebar menu, in any auto-index, or in breadcrumbs
+- its text is not added to the search index
+- `ursa serve` returns 404 for anything under it, matching what `generate`
+  produces
+
+The files stay where they are in the source tree; the site simply behaves as
+though they were not there.
+
+This differs from `--exclude` in scope and in lifetime: `--exclude` is a flag on
+one invocation, useful for a one-off or a per-environment build, while
+`config.json` travels with the content and applies to every build and every
+person who checks the repo out.
+
+`config.json` accepts a few other keys, all of which apply to the folder it
+sits in:
+
+| Key | Type | Meaning |
+| --- | --- | --- |
+| `hidden` | boolean | Ignore this folder and its subtree entirely (above) |
+| `label` | string | Name to show for this folder in menus and indices |
+| `icon` | string | URL of an icon to show beside it in the menu |
+| `openMenuItems` | string[] | Root `config.json` only: folders to expand by default |
+
 ### Large Workloads
 
 For sites with many documents (hundreds or thousands), you may need to increase Node.js memory limits:

package/bin/ursa.js

@@ -54,6 +54,12 @@ yargs(hideBin(process.argv))
         .option('promote-changelog', {
           describe: 'Path to a markdown file to render at the output root (sibling of index.html)',
           type: 'string'
+        })
+        .option('json-only', {
+          alias: 'j',
+          describe: 'Emit only the .json data files — no HTML, XML, images, static assets, search indices or menu data',
+          type: 'boolean',
+          default: false
         });
     },
     async (argv) => {
@@ -64,7 +70,8 @@ yargs(hideBin(process.argv))
       const exclude = argv.exclude || null;
       const clean = argv.clean;
       const promoteChangelog = argv['promote-changelog'] || null;
-      
+      const jsonOnly = argv['json-only'];
+
       console.log(`Generating site from ${source} to ${output} using meta from ${meta}`);
       if (whitelist) {
         console.log(`Using whitelist: ${whitelist}`);
@@ -75,7 +82,10 @@ yargs(hideBin(process.argv))
       if (clean) {
         console.log(`Clean build: ignoring cached hashes`);
       }
-      
+      if (jsonOnly) {
+        console.log(`JSON-only build: emitting .json data files only`);
+      }
+
       let promoted = { stagedFile: null, cleanup: async () => {} };
       try {
         promoted = await stagePromotedChangelog({ changelogPath: promoteChangelog, sourceDir: source });
@@ -85,7 +95,8 @@ yargs(hideBin(process.argv))
           _output: output,
           _whitelist: whitelist,
           _exclude: exclude,
-          _clean: clean
+          _clean: clean,
+          _jsonOnly: jsonOnly
         });
         console.log('Site generation completed successfully!');
       } catch (error) {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@kenjura/ursa",
   "author": "Andrew London <andrew@kenjura.com>",
   "type": "module",
-  "version": "0.93.0",
+  "version": "0.95.0",
   "description": "static site generator from MD/wikitext/YML",
   "main": "lib/index.js",
   "bin": {

package/src/dev.js

@@ -372,6 +372,15 @@ async function renderDocument(urlPath) {
   }
   
   const { sourcePath, type } = resolved;
+
+  // `hidden: true` means the folder takes no part in the build. `generate`
+  // writes nothing for it, so serving it on demand would make `serve` and
+  // `generate` disagree — the page works all through development and 404s in
+  // production, the exact failure mode this is meant to prevent.
+  if (isFolderHidden(dirname(sourcePath), source)) {
+    return null;
+  }
+
   const ext = type;
   const base = basename(sourcePath, ext);
   const dir = addTrailingSlash(dirname(sourcePath)).replace(source, "");
@@ -834,6 +843,26 @@ export async function dev({
   app.use(async (req, res, next) => {
     const url = req.url;
     
+    // Nothing under a folder that config.json marks `hidden: true` is served.
+    //
+    // This gate sits ahead of everything, including the `express.static`
+    // fallbacks mounted below — falling through with `next()` would just hand
+    // the file to them. `generate` writes no output for a hidden folder, so
+    // anything served here would work all through development and 404 in
+    // production, which is precisely what the setting exists to avoid.
+    let requestedSourcePath = null;
+    try {
+      requestedSourcePath = join(sourceDir, decodeURIComponent(url.split('?')[0]));
+    } catch (e) {
+      // Malformed percent-encoding — not a path we can classify; let it fall through
+    }
+    // Tested against the path itself, not its parent: `/foo/_art/` and
+    // `/foo/_art/index.html` must both be refused, and a file simply has no
+    // config.json of its own, so the ancestors decide either way.
+    if (requestedSourcePath && isFolderHidden(requestedSourcePath, sourceDir)) {
+      return res.status(404).send('<h1>404 Not Found</h1>');
+    }
+    
     // Handle search index requests
     if (url === '/public/search-index.json' || url === '/public/fulltext-index.json') {
       if (!devState.searchReady) {

package/src/helper/__test__/folderConfig.test.js

@@ -0,0 +1,89 @@
+import { join } from "path";
+import { mkdtemp, mkdir, writeFile, rm } from "fs/promises";
+import { tmpdir } from "os";
+import {
+  clearConfigCache,
+  isFolderHidden,
+  isFolderSelfHidden,
+} from "../folderConfig.js";
+
+let source;
+beforeEach(async () => {
+  source = await mkdtemp(join(tmpdir(), "ursa-folderconfig-"));
+  clearConfigCache();
+});
+afterEach(async () => {
+  await rm(source, { recursive: true, force: true });
+});
+
+async function hide(...segments) {
+  const dir = join(source, ...segments);
+  await mkdir(dir, { recursive: true });
+  await writeFile(join(dir, "config.json"), JSON.stringify({ hidden: true }));
+  return dir;
+}
+
+describe("isFolderHidden", () => {
+  it("matches the hidden folder itself", async () => {
+    const art = await hide("everdew", "_art");
+    expect(isFolderHidden(art, source)).toBe(true);
+  });
+
+  it("matches a descendant folder of a hidden folder", async () => {
+    await hide("everdew", "_art");
+    const nested = join(source, "everdew", "_art", "prompts", "people");
+    await mkdir(nested, { recursive: true });
+    expect(isFolderHidden(nested, source)).toBe(true);
+  });
+
+  it("matches file paths, not just directories", async () => {
+    // The build filters one list holding both files and directories through
+    // this predicate, so a file must resolve via its ancestors.
+    await hide("everdew", "_art");
+    expect(
+      isFolderHidden(join(source, "everdew", "_art", "prompts.md"), source)
+    ).toBe(true);
+    expect(
+      isFolderHidden(join(source, "everdew", "_art", "img", "map.png"), source)
+    ).toBe(true);
+  });
+
+  it("leaves siblings and ancestors of a hidden folder visible", async () => {
+    await hide("everdew", "_art");
+    await mkdir(join(source, "everdew", "people"), { recursive: true });
+    expect(isFolderHidden(join(source, "everdew", "people"), source)).toBe(false);
+    expect(isFolderHidden(join(source, "everdew"), source)).toBe(false);
+    expect(
+      isFolderHidden(join(source, "everdew", "people", "alice.md"), source)
+    ).toBe(false);
+  });
+
+  it("ignores a config.json that does not set hidden", async () => {
+    const dir = join(source, "everdew");
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, "config.json"), JSON.stringify({ label: "Everdew" }));
+    expect(isFolderHidden(dir, source)).toBe(false);
+  });
+
+  it("tolerates a trailing slash on the docroot", async () => {
+    const art = await hide("everdew", "_art");
+    expect(isFolderHidden(art, source + "/")).toBe(true);
+  });
+});
+
+describe("isFolderSelfHidden", () => {
+  it("is true only for the folder carrying the config, not its descendants", async () => {
+    const art = await hide("everdew", "_art");
+    const nested = join(art, "prompts");
+    await mkdir(nested, { recursive: true });
+
+    expect(isFolderSelfHidden(art)).toBe(true);
+    expect(isFolderSelfHidden(nested)).toBe(false);
+  });
+
+  it("is false for a folder with no config.json", async () => {
+    const dir = join(source, "people");
+    await mkdir(dir, { recursive: true });
+    expect(isFolderSelfHidden(dir)).toBe(false);
+  });
+});

package/src/helper/automenu.js

@@ -218,8 +218,10 @@ function buildMenuData(tree, source, validPaths, parentPath = '', includeDebug =
       }
     }
     
-    // Check if this folder is hidden via config.json
-    if (hasChildren && isFolderHidden(item.path, source)) {
+    // Check if this folder is hidden via config.json.
+    // Not gated on hasChildren: a hidden folder is ignored whether or not the
+    // tree walker found children under it.
+    if (isFolderHidden(item.path, source)) {
       continue; // Skip hidden folders
     }
     

package/src/helper/build/__test__/autoIndex.test.js

@@ -3,6 +3,7 @@ import { mkdtemp, mkdir, writeFile, rm, readFile } from "fs/promises";
 import { existsSync } from "fs";
 import { tmpdir } from "os";
 import { generateAutoIndices, generateAutoIndexHtmlFromSource } from "../autoIndex.js";
+import { clearConfigCache } from "../../folderConfig.js";
 
 let tempDir;
 let source;
@@ -160,3 +161,69 @@ describe("auto-index naming matches the automenu", () => {
     expect(rootIndex).toContain('<a href="bnw/index.html">BNW - Brave New World</a>');
   });
 });
+
+describe("folders ignored via config.json { hidden: true }", () => {
+  beforeEach(() => {
+    // getFolderConfig memoizes per absolute path; temp dirs are unique per
+    // test, but clearing keeps the cache from growing across the suite.
+    clearConfigCache();
+  });
+
+  it("omits a hidden folder from an auto-index built from source", async () => {
+    await mkdir(join(source, "_art"), { recursive: true });
+    await writeFile(join(source, "_art", "config.json"), JSON.stringify({ hidden: true }));
+    await writeFile(join(source, "_art", "prompts.md"), "# Prompts\n");
+    await mkdir(join(source, "people"), { recursive: true });
+    await writeFile(join(source, "people", "alice.md"), "# Alice\n");
+
+    const html = await generateAutoIndexHtmlFromSource(source, 2);
+
+    expect(html).toContain("people");
+    expect(html).not.toContain("_art");
+    expect(html).not.toContain("prompts");
+  });
+
+  it("omits a hidden folder even when stale output for it still exists", async () => {
+    // A folder generated before it was hidden leaves files behind in output.
+    // The listing is built from output, so without a source-side check the
+    // hidden folder would reappear in the index.
+    await mkdir(join(source, "_art"), { recursive: true });
+    await writeFile(join(source, "_art", "config.json"), JSON.stringify({ hidden: true }));
+    await mkdir(join(source, "people"), { recursive: true });
+    await writeFile(join(source, "people", "alice.md"), "# Alice\n");
+
+    await mkdir(join(output, "_art"), { recursive: true });
+    await writeFile(join(output, "_art", "prompts.html"), "<html><body>stale</body></html>");
+    await mkdir(join(output, "people"), { recursive: true });
+    await writeFile(join(output, "people", "alice.html"), "<html><body>Alice</body></html>");
+
+    const progress = makeProgress();
+    await runAutoIndices(
+      [source, join(source, "people")],
+      [join(source, "people", "alice.md")],
+      progress
+    );
+
+    const index = await readFile(join(output, "index.html"), "utf8");
+    expect(index).toContain("people");
+    expect(index).not.toContain("_art");
+  });
+
+  it("does not count documents inside a hidden subfolder when deciding a folder has content", async () => {
+    // `notes` holds nothing but a hidden subfolder, so it produces no pages
+    // and must not be linked as though it did.
+    await mkdir(join(source, "notes", "_art"), { recursive: true });
+    await writeFile(
+      join(source, "notes", "_art", "config.json"),
+      JSON.stringify({ hidden: true })
+    );
+    await writeFile(join(source, "notes", "_art", "prompts.md"), "# Prompts\n");
+    await mkdir(join(source, "people"), { recursive: true });
+    await writeFile(join(source, "people", "alice.md"), "# Alice\n");
+
+    const html = await generateAutoIndexHtmlFromSource(source, 2);
+
+    expect(html).toContain("people");
+    expect(html).not.toContain("notes");
+  });
+});

package/src/helper/build/autoIndex.js

@@ -8,7 +8,7 @@ import { findAllScriptJs } from "../findScriptJs.js";
 import { addTimestampToHtmlStaticRefs } from "./cacheBust.js";
 import { isMetadataOnly, extractMetadata, getAutoIndexConfig } from "../metadataExtractor.js";
 import { getCustomMenuForFile } from "./menu.js";
-import { getFolderConfig } from "../folderConfig.js";
+import { getFolderConfig, isFolderSelfHidden } from "../folderConfig.js";
 import {
   toDisplayName,
   getFolderLabel,
@@ -26,11 +26,18 @@ const OUTPUT_DOC_EXTENSIONS = ['.html'];
 
 /**
  * Recursively check if a directory contains any document files.
+ *
+ * Documents inside a config-hidden subfolder do not count: they produce no
+ * output, so a folder whose only contents are hidden must not be linked as if
+ * it had pages. When `dir` is an output directory, pass the matching source
+ * directory as `sourceDir` — the config.json lives in the source tree.
+ *
  * @param {string} dir - Directory path to check
  * @param {string[]} extensions - File extensions that count as documents
+ * @param {string|null} [sourceDir=dir] - Matching source directory, for hidden lookups
  * @returns {Promise<boolean>} True if the directory (or any subdirectory) contains at least one document
  */
-async function directoryHasDocuments(dir, extensions) {
+async function directoryHasDocuments(dir, extensions, sourceDir = dir) {
   try {
     const children = await readdir(dir, { withFileTypes: true });
     for (const child of children) {
@@ -38,7 +45,9 @@ async function directoryHasDocuments(dir, extensions) {
       const fullPath = join(dir, child.name);
       if (child.isDirectory()) {
         if (child.name === 'img') continue;
-        if (await directoryHasDocuments(fullPath, extensions)) return true;
+        if (sourceDir && isFolderSelfHidden(join(sourceDir, child.name))) continue;
+        const childSource = sourceDir ? join(sourceDir, child.name) : null;
+        if (await directoryHasDocuments(fullPath, extensions, childSource)) return true;
       } else {
         const ext = extname(child.name).toLowerCase();
         if (extensions.includes(ext)) return true;
@@ -111,6 +120,9 @@ export async function generateAutoIndexHtml(dir, depth = 1, currentDepth = 0, pa
         if (child.name === 'index.html') return false;
         // Skip img folders (contain images, not content)
         if (child.isDirectory() && child.name === 'img') return false;
+        // Skip folders config.json marks hidden — they are ignored entirely,
+        // so a stale output directory must not resurrect them in a listing
+        if (child.isDirectory() && sourceDir && isFolderSelfHidden(join(sourceDir, child.name))) return false;
         // Include directories and html files
         return child.isDirectory() || child.name.endsWith('.html');
       })
@@ -131,7 +143,8 @@ export async function generateAutoIndexHtml(dir, depth = 1, currentDepth = 0, pa
       // Skip directories that contain no documents
       if (isDir) {
         const childDir = join(dir, child.name);
-        if (!await directoryHasDocuments(childDir, OUTPUT_DOC_EXTENSIONS)) continue;
+        const childSource = sourceDir ? join(sourceDir, child.name) : null;
+        if (!await directoryHasDocuments(childDir, OUTPUT_DOC_EXTENSIONS, childSource)) continue;
       }
       // Use pathPrefix to ensure hrefs are correct relative to the document root
       const childPath = pathPrefix ? `${pathPrefix}/${child.name}` : child.name;
@@ -186,6 +199,8 @@ export async function generateAutoIndexHtmlFromSource(sourceDir, depth = 1, curr
         if (child.name.match(/^index\.(md|mdx|txt|yml|html)$/i)) return false;
         // Skip img folders (contain images, not content)
         if (child.isDirectory() && child.name === 'img') return false;
+        // Skip folders config.json marks hidden — they produce no output
+        if (child.isDirectory() && isFolderSelfHidden(join(sourceDir, child.name))) return false;
         // Include directories and article files (md, mdx, txt, yml, html)
         return child.isDirectory() || child.name.match(/\.(md|mdx|txt|yml|html)$/i);
       })
@@ -362,6 +377,8 @@ export async function generateAutoIndices(output, directories, source, templates
             // Skip hidden files and index alternates we just checked
             if (child.name.startsWith('.')) return false;
             if (child.name === 'index.html') return false;
+            // Skip folders config.json marks hidden — they produce no output
+            if (child.isDirectory() && isFolderSelfHidden(join(sourceDir, child.name))) return false;
             // Include directories and html files
             return child.isDirectory() || child.name.endsWith('.html');
           })
@@ -377,7 +394,7 @@ export async function generateAutoIndices(output, directories, source, templates
         for (const { child, isDir, label } of filteredItems) {
           if (isDir) {
             const childDir = join(dir, child.name);
-            if (!await directoryHasDocuments(childDir, OUTPUT_DOC_EXTENSIONS)) continue;
+            if (!await directoryHasDocuments(childDir, OUTPUT_DOC_EXTENSIONS, join(sourceDir, child.name))) continue;
           }
           // For directories, link to /folder/index.html; for files, use the filename directly
           const href = isDir ? `${child.name}/index.html` : child.name;

package/src/helper/folderConfig.js

@@ -11,9 +11,16 @@ const configCache = new Map();
  * {
  *   label?: string,       // Custom label for menu display
  *   icon?: string,        // URL to icon image for menu
- *   hidden?: boolean,     // If true, hide from menu and don't generate files
+ *   hidden?: boolean,     // If true, ignore the folder entirely (see below)
  *   openMenuItems?: string[]  // (root only) Array of folder names to expand by default
  * }
+ * 
+ * `hidden: true` means *ignored*, not merely unlisted. The folder and its
+ * whole subtree take no part in the build: no HTML is rendered from its
+ * documents, its images and other static assets are not copied, it does not
+ * appear in the sidebar menu, in any auto-index, in breadcrumbs, or in the
+ * search index, and `ursa serve` will not render its pages on demand. The
+ * files stay in the docroot; the site behaves as if they were not there.
  */
 
 /**
@@ -60,10 +67,33 @@ export function getRootConfig(sourceRoot) {
 }
 
 /**
- * Check if a folder or any of its ancestors is hidden via config.json
- * @param {string} folderPath - Absolute path to check
+ * True when this exact folder's own config.json says `hidden: true`, ignoring
+ * its ancestors.
+ *
+ * Use this where the ancestors have already been ruled out — walking a tree
+ * top-down, say, where reaching a node means every folder above it was
+ * visible. It needs no docroot, which is what makes it usable in the
+ * auto-index builders, where only the folder being listed is known.
+ *
+ * @param {string} folderPath - Absolute path to a folder
+ * @returns {boolean} True if that folder is marked hidden
+ */
+export function isFolderSelfHidden(folderPath) {
+  return getFolderConfig(folderPath.replace(/\/$/, ''))?.hidden === true;
+}
+
+/**
+ * Check if a path lies in a folder — its own, or any ancestor up to the
+ * docroot — that config.json marks `hidden: true`.
+ *
+ * Accepts file paths as well as directories: the walk starts at `folderPath`
+ * itself, and a file simply has no config.json of its own, so the first step
+ * misses and the ancestors decide. That is what lets the build filter a mixed
+ * list of files and directories through one predicate.
+ *
+ * @param {string} folderPath - Absolute path to check (file or directory)
  * @param {string} sourceRoot - The source root directory (stop checking at this level)
- * @returns {boolean} True if this folder should be hidden
+ * @returns {boolean} True if this path should be ignored
  */
 export function isFolderHidden(folderPath, sourceRoot) {
   let currentPath = folderPath.replace(/\/$/, '');