for-humanity 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## Unreleased
+
+## 0.4.0 — 2026-10-04
+
+- Copy explicitly referenced local images and supported attachments to fingerprinted asset URLs, resolving paths relative to their Markdown files in both build and dev.
+- Support reference-style images and raw HTML image sources, preserve query/hash suffixes, and reject missing files, unsupported local image formats and paths or symlinks outside the document root.
+- Reload referenced image and attachment changes in dev while retaining the previous valid document and resource map after failed processing.
+- Mark only the current table-of-contents anchor as active, with `aria-current="location"`, while retaining the tree path through its ancestors.
+- Add image documentation, purpose-based authoring guidance and fictional design and research examples.
+- Keep legacy `type: document` and `type: blueprint` inputs compatible, recommend omitting `type`, and focus the roadmap on reusable visualization and theme modules rather than a dedicated Blueprint renderer.
+
+## 0.3.0 — 2026-10-04
+
+- Support nested document pages with optional `parent` IDs, preserving existing groups and document URLs.
+- Resolve `./` and `../` parent references relative to document files so project folders can also be used as document roots.
+- Reject missing parents, self references, parent cycles and parent links across different group paths.
+- Extend active, hover and keyboard focus tree paths through clickable parent documents.
+- Distinguish sidebar groups from document links and page headings, and rename the table of contents to "On this page" with a gray label matching the groups.
+- Clarify trunk-based development, site deployment and package release policy.
+
 ## 0.2.1 — 2026-10-04
 
 - Fingerprint stylesheet and browser-script URLs so new pages cannot reuse assets cached from an older deployment.

package/README.md

@@ -33,7 +33,7 @@ Write Markdown. Keep the context. Share a static site.
 Node.js 22 or later and pnpm. Install the CLI in your document project:
 
 ```sh
-pnpm add -D --save-exact for-humanity@0.2.1
+pnpm add -D --save-exact for-humanity@0.4.0
 mkdir docs
 ```
 
@@ -52,7 +52,7 @@ pnpm exec for-humanity preview docs
 
 If your Markdown files are in the project root, use `.` instead of `docs`. The root `README.md` becomes the home page; root `AGENTS.md` and `CLAUDE.md` stay out of the site.
 
-Version `0.2.1` supports `dev`, `build` and `preview`. `init` is planned; see the [Roadmap](https://github.com/minu-ha/for-humanity/blob/main/templates/document/roadmap.md) and [Changelog](https://github.com/minu-ha/for-humanity/blob/main/CHANGELOG.md).
+Version `0.4.0` supports `dev`, `build` and `preview`. `init` is planned; see the [Roadmap](https://github.com/minu-ha/for-humanity/blob/main/templates/document/roadmap.md) and [Changelog](https://github.com/minu-ha/for-humanity/blob/main/CHANGELOG.md).
 Cloudflare Pages can host the generated site. See [Deployment](https://github.com/minu-ha/for-humanity/blob/main/templates/document/deployment.md) for the build settings.
 
 ### Develop the kit
@@ -74,7 +74,7 @@ pnpm preview    # Preview the static site
 pnpm build:pages # Add Cloudflare Pages headers and a 404 page
 ```
 
-Changes pushed to `main` update the documentation site. A stable version tag such as `v0.2.1` runs checks, publishes the package to npm, then creates a GitHub Release with the same package file.
+Changes pushed to `main` update the documentation site. A stable version tag such as `v0.4.0` runs checks, publishes the package to npm, then creates a GitHub Release with the same package file.
 The npm README updates with each package release. See [Maintenance](https://github.com/minu-ha/for-humanity/blob/main/templates/document/maintenance.md#packaging-and-release) for the release steps.
 
 ## Make it yours
@@ -95,6 +95,7 @@ export default {
 See [Commands](https://github.com/minu-ha/for-humanity/blob/main/templates/document/commands.md) for using another document folder, and [Settings](https://github.com/minu-ha/for-humanity/blob/main/templates/document/settings.md) for configuration.
 Each document other than the root README chooses a `group` and optional `order`. Pages stay independent; groups do not need parent documents or nested folders. Document names may share the same first letter.
 Use `group: Guide` for one group or `group: [Projects, Example project, Research]` for nested navigation. Group paths do not change document URLs.
+Use `parent: writing` to place a document below another document in the same group. File-relative references such as `parent: ./readme` also work. Parent pages remain clickable and each page keeps its own URL; see [Navigation](https://github.com/minu-ha/for-humanity/blob/main/templates/document/navigation.md).
 
 ## Write with context
 
@@ -108,7 +109,7 @@ The contract, code or reasoning behind the visible result.
 :::
 ```
 
-[Parts](https://github.com/minu-ha/for-humanity/blob/main/templates/document/parts.md) pairs source examples with their rendered results. The [Blueprint sample](https://github.com/minu-ha/for-humanity/blob/main/templates/document/blueprint.md) uses a fictional reading-list app to show a screen flow, decisions, open questions and illustrative API contracts.
+[Parts](https://github.com/minu-ha/for-humanity/blob/main/templates/document/parts.md) pairs source examples with their rendered results. The [Design example](https://github.com/minu-ha/for-humanity/blob/main/templates/document/blueprint.md) uses a fictional reading-list app to show a screen flow, decisions, open questions and illustrative API contracts.
 
 ## Documentation
 
@@ -118,7 +119,7 @@ The contract, code or reasoning behind the visible result.
 | Guide | [Writing](https://github.com/minu-ha/for-humanity/blob/main/templates/document/writing.md) · [Parts](https://github.com/minu-ha/for-humanity/blob/main/templates/document/parts.md) · [Settings](https://github.com/minu-ha/for-humanity/blob/main/templates/document/settings.md) |
 | Reference | [API](https://github.com/minu-ha/for-humanity/blob/main/templates/document/api.md) |
 | Releases | [Official releases](https://github.com/minu-ha/for-humanity/blob/main/templates/document/releases.md) · [Changelog](https://github.com/minu-ha/for-humanity/blob/main/templates/document/changelog.md) |
-| Examples | [Fictional Blueprint](https://github.com/minu-ha/for-humanity/blob/main/templates/document/blueprint.md) |
+| Examples | [Fictional design example](https://github.com/minu-ha/for-humanity/blob/main/templates/document/blueprint.md) |
 | Development | [Architecture](https://github.com/minu-ha/for-humanity/blob/main/templates/document/architecture.md) · [Design](https://github.com/minu-ha/for-humanity/blob/main/templates/document/design.md) · [Maintenance](https://github.com/minu-ha/for-humanity/blob/main/templates/document/maintenance.md) · [Roadmap](https://github.com/minu-ha/for-humanity/blob/main/templates/document/roadmap.md) |
 
 ## License

package/dist/cli.css

@@ -306,8 +306,27 @@
   display: block;
   padding: var(--app-space-tree-row) 0 var(--app-space-tree-row) calc(var(--app-space-tree-indent) + var(--app-space-inline));
   color: var(--app-color-text-muted);
-  font-size: var(--app-font-size-label);
+  font-size: var(--app-font-size-group);
+  line-height: calc(var(--app-font-size-dense) * var(--app-line-height-tight));
+  overflow-wrap: anywhere;
+  &::before {
+    position: absolute;
+    top: calc(0.5lh + var(--app-space-tree-row));
+    left: 0;
+    width: var(--app-space-tree-indent);
+    border-top: 1px solid var(--app-color-border-soft);
+    content: "";
+    pointer-events: none;
+  }
+}
+.wg_shellNavList__link {
+  position: relative;
+  display: block;
+  padding: var(--app-space-tree-row) 0 var(--app-space-tree-row) calc(var(--app-space-tree-indent) + var(--app-space-inline));
+  color: var(--app-color-link);
+  font-size: var(--app-font-size-dense);
   line-height: var(--app-line-height-tight);
+  text-decoration: none;
   overflow-wrap: anywhere;
   &::before {
     position: absolute;
@@ -318,6 +337,26 @@
     content: "";
     pointer-events: none;
   }
+  &:where(:hover) {
+    text-decoration: underline;
+  }
+  &:where(:hover)::before {
+    border-top-color: currentcolor;
+  }
+  &:where(:focus-visible) {
+    outline: none;
+    text-decoration: underline;
+  }
+  &:where(:focus-visible)::before {
+    border-top-color: currentcolor;
+  }
+}
+.wg_shellNavList__link--active {
+  color: var(--app-color-link);
+  font-weight: var(--app-font-weight-active);
+  &::before {
+    border-top-color: currentcolor;
+  }
 }
 .wg_shellNavList__item {
   display: flow-root;
@@ -345,77 +384,47 @@
     pointer-events: none;
   }
   &:where(:hover)::after {
-    border-left-color: var(--app-color-text-strong);
+    border-left-color: var(--app-color-link);
   }
   &:where(:has(:focus-visible))::after {
-    border-left-color: var(--app-color-text-strong);
+    border-left-color: var(--app-color-link);
   }
   &:where(:has(~ .wg_shellNavList__item:hover))::before {
-    border-left-color: var(--app-color-text-strong);
+    border-left-color: var(--app-color-link);
   }
   &:where(:has(~ .wg_shellNavList__item :focus-visible))::before {
-    border-left-color: var(--app-color-text-strong);
+    border-left-color: var(--app-color-link);
   }
   & > .wg_shellNavList__root {
     margin-left: var(--app-space-tree-indent);
   }
   &:where(:hover) > .wg_shellNavList__branch::before {
-    border-top-color: var(--app-color-text-strong);
+    border-top-color: var(--app-color-link);
   }
   &:where(:has(:focus-visible)) > .wg_shellNavList__branch::before {
-    border-top-color: var(--app-color-text-strong);
+    border-top-color: var(--app-color-link);
+  }
+  &:where(:hover) > .wg_shellNavList__link::before {
+    border-top-color: var(--app-color-link);
+  }
+  &:where(:has(:focus-visible)) > .wg_shellNavList__link::before {
+    border-top-color: var(--app-color-link);
   }
 }
 .wg_shellNavList__item--trail {
   &::before {
-    border-left-color: var(--app-color-text-strong);
+    border-left-color: var(--app-color-link);
   }
 }
 .wg_shellNavList__item--current {
   &::after {
-    border-left-color: var(--app-color-text-strong);
+    border-left-color: var(--app-color-link);
   }
   & > .wg_shellNavList__branch::before {
-    border-top-color: var(--app-color-text-strong);
-  }
-}
-.wg_shellNavList__link {
-  position: relative;
-  display: block;
-  padding: var(--app-space-tree-row) 0 var(--app-space-tree-row) calc(var(--app-space-tree-indent) + var(--app-space-inline));
-  color: var(--app-color-text);
-  font-size: var(--app-font-size-dense);
-  line-height: var(--app-line-height-tight);
-  text-decoration: none;
-  overflow-wrap: anywhere;
-  &::before {
-    position: absolute;
-    top: calc(0.5lh + var(--app-space-tree-row));
-    left: 0;
-    width: var(--app-space-tree-indent);
-    border-top: 1px solid var(--app-color-border-soft);
-    content: "";
-    pointer-events: none;
-  }
-  &:where(:hover) {
-    text-decoration: underline;
+    border-top-color: var(--app-color-link);
   }
-  &:where(:hover)::before {
-    border-top-color: currentcolor;
-  }
-  &:where(:focus-visible) {
-    outline: none;
-    text-decoration: underline;
-  }
-  &:where(:focus-visible)::before {
-    border-top-color: currentcolor;
-  }
-}
-.wg_shellNavList__link--active {
-  color: var(--app-color-text-strong);
-  font-weight: var(--app-font-weight-active);
-  &::before {
-    border-top-color: currentcolor;
+  & > .wg_shellNavList__link::before {
+    border-top-color: var(--app-color-link);
   }
 }
 
@@ -432,7 +441,8 @@
 .wg_shellNav__group {
   margin: 0 0 4px;
   color: var(--app-color-text-muted);
-  font-size: var(--app-font-size-label);
+  font-size: var(--app-font-size-group);
+  line-height: calc(var(--app-font-size-dense) * var(--app-line-height-tight));
   text-box: trim-start cap alphabetic;
 }
 
@@ -448,13 +458,14 @@
   margin-bottom: var(--app-space-inline);
   color: var(--app-color-text-muted);
   font-size: var(--app-font-size-label);
-  font-weight: var(--app-font-weight-mark);
+  font-weight: var(--app-font-weight-strong);
   letter-spacing: var(--app-letter-spacing-label);
 }
 .wg_shellToc__group {
   margin: var(--app-space-stack) 0 4px;
   color: var(--app-color-text-muted);
-  font-size: var(--app-font-size-label);
+  font-size: var(--app-font-size-group);
+  line-height: calc(var(--app-font-size-dense) * var(--app-line-height-tight));
 }
 .wg_shellToc__list {
   margin: 0 0 0 var(--app-space-tree-inset);
@@ -465,7 +476,7 @@
   position: relative;
   display: block;
   padding: var(--app-space-tree-row) 0 var(--app-space-tree-row) calc(var(--app-space-tree-indent) + var(--app-space-inline));
-  color: var(--app-color-text-muted);
+  color: var(--app-color-text);
   font-size: var(--app-font-size-dense);
   line-height: var(--app-line-height-tight);
   text-decoration: none;
@@ -611,7 +622,7 @@
   position: relative;
   display: block;
   padding: var(--app-space-tree-row) 0 var(--app-space-tree-row) calc(var(--app-space-tree-indent) + var(--app-space-inline));
-  color: var(--app-color-text-muted);
+  color: var(--app-color-text);
   font-size: var(--app-font-size-detail);
   line-height: var(--app-line-height-tight);
   text-decoration: none;
@@ -702,6 +713,7 @@
     sans-serif;
   --app-font-mono: "JetBrains Mono Variable", var(--app-font-sans);
   --app-font-brand: "Architects Daughter", var(--app-font-sans);
+  --app-font-size-group: 11px;
   --app-font-size-label: 12px;
   --app-font-size-detail: 12px;
   --app-font-size-dense: 12px;
@@ -711,7 +723,7 @@
   --app-font-size-section: 14px;
   --app-font-size-title: 16px;
   --app-font-weight-mark: 400;
-  --app-font-weight-active: 500;
+  --app-font-weight-active: 600;
   --app-font-weight-strong: 600;
   --app-font-weight-title: 600;
   --app-line-height-title: 1.5;