@kenjura/ursa 0.90.1 → 0.95.0

package/CHANGELOG.md

@@ -1,3 +1,81 @@
+# 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
+
+`menu-label` now renames a folder everywhere it appears, not just in the sidebar.
+
+A folder could already override its menu label — `menu-label` in its `index.md` frontmatter, or `label` in its `config.json` — and the site-wide menu honoured it. Nothing else did. A folder called `bnw` labelled "BNW - Brave New World" in the sidebar was still "Bnw" in the auto-index listing of its parent, "Bnw" in the `<h1>` and `<title>` of its own generated index page, and "Bnw" in every breadcrumb trail passing through it. The label was doing a quarter of its job, and there was no way to fix the other three without renaming the folder on disk.
+
+- **Auto-index listings resolve labels the same way the menu does**: `menu-label` frontmatter, then `config.json` `label`, then the folder name. This covers all three listing paths — the inline listing from `generate-auto-index: true`, the fallback index generated for folders without one, and the output-scanning variant.
+- **Individual documents honour `menu-label` too**, so a single article can be renamed in a listing without renaming its file.
+- **Auto-generated index pages take the folder's label** for their `<h1>` and `<title>`, instead of the raw folder name.
+- **Breadcrumbs use folder labels** for every folder segment in the trail. The current page's own crumb now prefers its `menu-label` over its `title`; with neither, nothing changes.
+- **`menu-sort-as` orders auto-index listings**, matching how it already orders the menu. Folders still sort ahead of files.
+
+One naming change reaches folders with no label at all. Auto-index entries and breadcrumbs used to title-case names by lowercasing everything after the first letter, so a folder named `SoL` rendered as "Sol" and `WWII` as "Wwii". They now use the menu's own rule, which leaves interior capitals alone — the two places agree, and the disagreement they had was the bug.
+
+The resolution rules live in `helper/menuLabels.js`, which the menu, the auto-index and the breadcrumbs all import, so the three cannot drift apart again.
+
+Auto-index pages still have no dependency edge to the documents they list, so on a warm incremental rebuild a label edit in one folder does not regenerate a sibling listing that names it. That predates this change — adding or renaming a document went stale the same way — and `--clean` or a full generate is unaffected.
+
+# 0.92.0
+2026-08-27
+
+Upgrading ursa now invalidates the build cache, so an upgrade takes effect without `--clean`.
+
+`.ursa/` caches a content hash per source document, and a document whose hash is unchanged is skipped entirely. But the hash only describes the *source*. It says nothing about the templates, renderers and asset bundles that turned that source into HTML — all of which live in ursa itself. So installing a new ursa over a warm cache left every unchanged document frozen at whatever the previous version produced: new template markup didn't appear, renderer fixes didn't apply, and even the ursa version in the page footer stayed at the old number. The workaround was to remember to run `--clean` after every upgrade, which is most of what made `--clean` feel mandatory in the first place.
+
+- **`.ursa/` is stamped with the ursa version that wrote it.** On a mismatch the whole directory is discarded — hashes, dependency graph, nav cache and search index together — and the build starts cold. Upgrades and downgrades both count; so does a cache left by a version too old to have written a stamp, and a stamp that can't be parsed.
+- **Matching stamps cost nothing.** A warm rebuild on the same version still skips every unchanged document, exactly as before.
+- **`--clean` is unaffected**, and leaves behind a stamp the next run accepts, so it no longer costs an extra cold build.
+
+This was the last unimplemented rule in the 0.76.0 cache-invalidation list; the other four (document, inherited `style.css`/`menu.md`, template, static asset) were already in place.
+
+# 0.91.0
+2026-08-27
+
+Ursa's built-in CSS is scoped with `@scope` and layered with `@layer`, so a site's own stylesheet no longer has to fight it.
+
+Styling a site had turned into a specificity war. Ursa's stylesheet is loaded before the site's, but it styles content through selectors like `article#main-content h1` — an ID and two elements — so a site author writing the obvious `h1 { … }` lost, and kept losing until they either copied Ursa's selectors or reached for `!important`. Worse, rules meant for the frame leaked into documents and rules meant for documents leaked into the frame, because everything shared one flat global scope.
+
+- **Content styles are layered.** Everything Ursa applies to a document body — headings, images, figures, the article box, the sticky headings — now lives in `@layer ursa.content`. A site's `style.css` is unlayered, and an unlayered declaration beats a layered one regardless of specificity, so `h1 { position: static }` or `#main-content { width: 1000px }` in a site stylesheet simply wins, at any specificity.
+- **Chrome is scoped, not layered.** The top bar, menus, widgets, search and footer sit in `@scope (body) to (#main-content > *, article > *, .ursa-unstyled)`, so none of it can reach into a document's own markup — and, being unlayered, a stray `a { … }` in a site stylesheet still can't wreck the navigation. Chrome's selectors are unchanged, so overriding them works the way it always did — with a more specific selector, since a scoped rule now wins a specificity tie against an unscoped one. Breadcrumbs, the image hover controls and the lightbox get their own scopes on the same terms, since they are Ursa's furniture even though they render inside — or on top of — the document.
+- **`class="ursa-unstyled"`** on any element puts it and everything inside it outside every one of Ursa's scopes. Not "override the defaults" — Ursa's CSS does not apply in there at all, down to the strike-through on dead links. The lightbox leaves images in there alone too, rather than injecting controls it has no styles for.
+- **Nothing looks different.** The reorganisation is a pure cascade change. Verified by diffing every computed property and every bounding box of every element, before and after, across four pages, both colour schemes, desktop and mobile widths, and eight interaction states (top menu, collapsed and open side menu, stuck headings, open widgets, search results, inactive links, open lightbox): zero differences outside `.ursa-unstyled`.
+
+Requires `@scope`: Chrome 118+, Safari 17.4+, Firefox 128+.
+
 # 0.90.1
 2026-08-29
 

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:
@@ -216,6 +283,41 @@ your-project/
 └── output/          # Generated site (created automatically)
 ```
 
+## Styling a Site
+
+Drop a `style.css` (or `style-ursa.css`, or `_style.css`) in any source folder and it applies to every document in that folder and below. Every such file from the docroot down to the document's own folder is included, nearest last, so a deeper file overrides a shallower one.
+
+Ursa's own stylesheet is scoped and layered so that your CSS wins without a fight:
+
+- **Document content** — headings, images, figures, the article box itself — is styled inside `@layer ursa.content`. Your stylesheet is unlayered, and an unlayered rule beats a layered one no matter how specific it is, so a plain `h1 { position: static }` or `#main-content { width: 1000px }` overrides whatever Ursa sets. No `article#main-content h1` escalation, no `!important`.
+- **Chrome** — the top bar, menus, widgets, search, footer, breadcrumbs, image hover controls and lightbox — is scoped but *not* layered, so a broad rule like `a { color: … }` in your stylesheet cannot bleed into the navigation. Overriding chrome works as it always did: use a more specific selector than the built-in one.
+- **Nothing built in reaches into content it shouldn't.** Chrome rules stop at the article's children; content rules stop at the article's edge.
+- **`class="ursa-unstyled"`** on any element puts it and its descendants outside every one of Ursa's scopes — none of Ursa's CSS applies in there at all, and the lightbox leaves images in there alone.
+
+This uses the CSS `@scope` and `@layer` rules: Chrome 118+, Safari 17.4+, Firefox 128+.
+
+### Styling one widget at a time
+
+The two widget panels are shared containers — the right-hand one holds the table
+of contents, search and profile in turn — so styling `.widget-dropdown` styles
+all of them at once. While a panel is open it carries `data-active-widget` naming
+whichever widget is showing, and the attribute is removed when it closes, so a
+site can give each one its own treatment:
+
+```css
+/* Only the table of contents; search and profile keep the default panel. */
+.widget-dropdown[data-active-widget="toc"] {
+  background: rgba(20, 24, 28, 0.78);
+  backdrop-filter: blur(10px);
+}
+```
+
+Both panels carry it: `#widget-dropdown` for the right-hand widgets (`toc`,
+`search`, `profile`) and `#widget-dropdown-left` for the left-hand ones
+(`recent-activity`, `suggested`). The value is the widget's `data-widget` name.
+Ursa uses this hook itself, to lay the TOC out along the bottom of the viewport
+on a narrow screen.
+
 ## Auto-Index Generation
 
 Ursa automatically generates index pages for folders that don't have one. You can also explicitly control auto-index generation in your index documents using frontmatter:

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) {