for-humanity 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.2.1 — 2026-10-04
+
+- Fingerprint stylesheet and browser-script URLs so new pages cannot reuse assets cached from an older deployment.
+- Cache fingerprinted CSS, scripts and fonts with immutable headers on Cloudflare Pages.
+
 ## 0.2.0 — 2026-10-04
 
 - Support nested navigation with `group` name arrays while keeping single-name groups compatible.

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.0
+pnpm add -D --save-exact for-humanity@0.2.1
 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.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).
+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).
 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.0` 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.2.1` 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

package/dist/cli.js

@@ -227,7 +227,7 @@ var WgShell = (props) => {
       /* @__PURE__ */ jsx5("style", { dangerouslySetInnerHTML: { __html: props.assets.fontCss } }),
       props.assets.preload.map((href) => /* @__PURE__ */ jsx5("link", { rel: "preload", href, as: "font", type: "font/woff2", crossOrigin: "" }, href)),
       /* @__PURE__ */ jsx5("script", { dangerouslySetInnerHTML: { __html: 'document.documentElement.style.scrollBehavior="auto"' } }),
-      /* @__PURE__ */ jsx5("link", { rel: "stylesheet", href: asset_style_path }),
+      /* @__PURE__ */ jsx5("link", { rel: "stylesheet", href: props.assets.stylePath }),
       props.assets.reload && /* @__PURE__ */ jsx5("script", { dangerouslySetInnerHTML: { __html: reloadScript } })
     ] }),
     /* @__PURE__ */ jsxs5("body", { className: clsx5("wg_shell__root"), children: [
@@ -261,7 +261,7 @@ var WgShell = (props) => {
         /* @__PURE__ */ jsx5("div", { className: clsx5("wg_shell__drawerContent"), "data-navigation-content": "" })
       ] }),
       /* @__PURE__ */ jsx5("img", { className: clsx5("wg_shell__cursorFace"), src: asset_favicon_path, width: "24", height: "24", alt: "", "aria-hidden": "true", draggable: false, "data-cursor-face": "" }),
-      /* @__PURE__ */ jsx5("script", { type: "module", src: asset_client_path })
+      /* @__PURE__ */ jsx5("script", { type: "module", src: props.assets.clientPath })
     ] })
   ] });
 };
@@ -1169,17 +1169,26 @@ var toErrorMessage = (error) => {
   return error instanceof Error ? error.message : String(error);
 };
 
-// src/util/font/to-font-css.ts
+// src/util/file/to-asset-path.ts
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
+import { posix as posix2 } from "node:path";
+var toAssetPath = (options) => {
+  const extension = posix2.extname(options.path);
+  return `${posix2.dirname(options.path)}/${posix2.basename(options.path, extension)}.${createHash("sha256").update(readFileSync(options.file)).digest("hex")}${extension}`;
+};
+
+// src/util/font/to-font-css.ts
+import { createHash as createHash2 } from "node:crypto";
+import { readFileSync as readFileSync2 } from "node:fs";
 import { basename, dirname as dirname2, extname as extname2, join as join3 } from "node:path";
 var toFontCss = (options) => {
   const files = /* @__PURE__ */ new Map();
-  const css = [...readFileSync(options.css, "utf8").matchAll(/@font-face\s*\{[^}]*\}/g)].map(
+  const css = [...readFileSync2(options.css, "utf8").matchAll(/@font-face\s*\{[^}]*\}/g)].map(
     (match) => match[0].replace(/font-display:\s*[^;]+;/g, `font-display: ${font_display_strategy};`).replace(/url\(([^)]+)\)/g, (_match, relativeUrl) => {
       const file = join3(dirname2(options.css), relativeUrl);
       const extension = extname2(file);
-      const hash = createHash("sha256").update(readFileSync(file)).digest("hex").slice(0, font_hash_length);
+      const hash = createHash2("sha256").update(readFileSync2(file)).digest("hex").slice(0, font_hash_length);
       const url = `${options.fontDir}/${basename(file, extension)}.${hash}${extension}`;
       files.set(url, file);
       return `url(${url})`;
@@ -1228,9 +1237,11 @@ var main = async () => {
     throw new Error(`${copy_error_font_preload}: ${font_sans_preload_file}`);
   }
   const fontCss = [sans.css, mono.css, brand.css].join("\n");
+  const stylePath = toAssetPath({ path: asset_style_path, file: join4(kitRoot, "dist/cli.css") });
+  const clientPath = toAssetPath({ path: asset_client_path, file: join4(kitRoot, "dist/client.js") });
   const files = new Map([
-    [asset_style_path, join4(kitRoot, "dist/cli.css")],
-    [asset_client_path, join4(kitRoot, "dist/client.js")],
+    [stylePath, join4(kitRoot, "dist/cli.css")],
+    [clientPath, join4(kitRoot, "dist/client.js")],
     [asset_favicon_path, join4(kitRoot, "src/asset/favicon.svg")],
     ...sans.files,
     ...mono.files,
@@ -1242,7 +1253,7 @@ var main = async () => {
   const app = createApp({
     site: siteConfig,
     store,
-    assets: { fontCss, preload: [...brand.files.keys(), sansPreload[0], ...mono.files.keys()], reload: command === "dev" }
+    assets: { stylePath, clientPath, fontCss, preload: [...brand.files.keys(), sansPreload[0], ...mono.files.keys()], reload: command === "dev" }
   });
   if (command === "build") {
     await rm(outDir, { recursive: true, force: true });

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "for-humanity",
-    "version": "0.2.0",
+    "version": "0.2.1",
     "description": "Documents written for humans to read: a docs kit with a sidebar, parts, sections and flowcharts, built on Hono and React",
     "keywords": [
         "docs",

package/src/cli.ts

@@ -25,6 +25,7 @@ import {readHome} from "@/content/read-home";
 import {createDevApp} from "@/dev";
 import {siteConfigSchema} from "@/type/site-config";
 import {toErrorMessage} from "@/util/error/to-error-message";
+import {toAssetPath} from "@/util/file/to-asset-path";
 import {toFontCss} from "@/util/font/to-font-css";
 
 const commands = ["dev", "build", "preview"];
@@ -82,9 +83,11 @@ const main = async () => {
     }
 
     const fontCss = [sans.css, mono.css, brand.css].join("\n");
+    const stylePath = toAssetPath({path: asset_style_path, file: join(kitRoot, "dist/cli.css")});
+    const clientPath = toAssetPath({path: asset_client_path, file: join(kitRoot, "dist/client.js")});
     const files = new Map([
-        [asset_style_path, join(kitRoot, "dist/cli.css")],
-        [asset_client_path, join(kitRoot, "dist/client.js")],
+        [stylePath, join(kitRoot, "dist/cli.css")],
+        [clientPath, join(kitRoot, "dist/client.js")],
         [asset_favicon_path, join(kitRoot, "src/asset/favicon.svg")],
         ...sans.files,
         ...mono.files,
@@ -96,7 +99,7 @@ const main = async () => {
     const app = createApp({
         site: siteConfig,
         store,
-        assets: {fontCss, preload: [...brand.files.keys(), sansPreload[0], ...mono.files.keys()], reload: command === "dev"},
+        assets: {stylePath, clientPath, fontCss, preload: [...brand.files.keys(), sansPreload[0], ...mono.files.keys()], reload: command === "dev"},
     });
 
     if (command === "build") {

package/src/component/widget/shell/wg-shell.tsx

@@ -4,7 +4,7 @@ import {toTocGroups} from "@/component/widget/shell/_function/to-toc-groups";
 import type {DocOutline} from "@/component/widget/shell/_type/doc-outline";
 import {WgShellNav} from "@/component/widget/shell/_wg-shell-nav";
 import {WgShellToc} from "@/component/widget/shell/_wg-shell-toc";
-import {asset_client_path, asset_favicon_path, asset_reload_path, asset_style_path} from "@/constant/asset";
+import {asset_favicon_path, asset_reload_path} from "@/constant/asset";
 import {copy_nav_close, copy_nav_open, copy_nav_title} from "@/constant/copy";
 import type {Doc} from "@/type/doc";
 import type {SiteAssets} from "@/type/site-assets";
@@ -71,7 +71,7 @@ export const WgShell = (props: WgShellProps) => {
                     <link key={href} rel="preload" href={href} as="font" type="font/woff2" crossOrigin="" />
                 ))}
                 <script dangerouslySetInnerHTML={{__html: 'document.documentElement.style.scrollBehavior="auto"'}} />
-                <link rel="stylesheet" href={asset_style_path} />
+                <link rel="stylesheet" href={props.assets.stylePath} />
                 {props.assets.reload && <script dangerouslySetInnerHTML={{__html: reloadScript}} />}
             </head>
             {/**
@@ -140,7 +140,7 @@ export const WgShell = (props: WgShellProps) => {
                     <div className={clsx("wg_shell__drawerContent")} data-navigation-content="" />
                 </dialog>
                 <img className={clsx("wg_shell__cursorFace")} src={asset_favicon_path} width="24" height="24" alt="" aria-hidden="true" draggable={false} data-cursor-face="" />
-                <script type="module" src={asset_client_path} />
+                <script type="module" src={props.assets.clientPath} />
             </body>
         </html>
     );

package/src/constant/asset.ts

@@ -8,12 +8,12 @@
 export const asset_dir = "_fh";
 
 /**
- * esbuild의 컴포넌트 CSS 묶음
+ * 내용 지문을 붙일 esbuild CSS의 기본 URL
  */
 export const asset_style_path = `/${asset_dir}/style.css`;
 
 /**
- * 테마·목차·hash 보정 브라우저 스크립트
+ * 내용 지문을 붙일 테마·목차·hash 보정 스크립트의 기본 URL
  */
 export const asset_client_path = `/${asset_dir}/client.js`;
 

package/src/content/read-docs.test.ts

@@ -6,6 +6,7 @@ import {test} from "node:test";
 import {renderToStaticMarkup} from "react-dom/server";
 import {createApp} from "@/app";
 import {WgShellNav} from "@/component/widget/shell/_wg-shell-nav";
+import {asset_client_path, asset_style_path} from "@/constant/asset";
 import {createProcessor} from "@/content/create-processor";
 import {readDocs} from "@/content/read-docs";
 import {readHome} from "@/content/read-home";
@@ -13,6 +14,17 @@ import {toDocGroups} from "@/content/to-doc-groups/to-doc-groups";
 import {docDataSchema} from "@/type/doc-data";
 import {siteConfigSchema} from "@/type/site-config";
 
+test("page resource URLs use the supplied content fingerprints instead of fixed cache keys", async () => {
+    const site = siteConfigSchema.parse({});
+    const assets = {fontCss: "", preload: [], reload: false, stylePath: "/_fh/style.abc123.css", clientPath: "/_fh/client.def456.js"};
+    const app = createApp({site, store: {docs: []}, assets});
+    const html = await (await app.request("/")).text();
+
+    assert.match(html, /rel="stylesheet" href="\/_fh\/style\.abc123\.css"/);
+    assert.match(html, /type="module" src="\/_fh\/client\.def456\.js"/);
+    assert.doesNotMatch(html, /(?:href|src)="\/_fh\/(?:style\.css|client\.js)"/);
+});
+
 test("documents with the same initial retain distinct URLs", async (t) => {
     const root = await mkdtemp(join(tmpdir(), "for-humanity-docs-"));
     const site = siteConfigSchema.parse({});
@@ -201,7 +213,7 @@ test("a plain root README renders at home and relative home links resolve from n
     ]);
 
     const [docs, home] = await Promise.all([readDocs({root, processor}), readHome({root, processor})]);
-    const app = createApp({site, store: {docs, home}, assets: {fontCss: "", preload: [], reload: false}});
+    const app = createApp({site, store: {docs, home}, assets: {stylePath: asset_style_path, clientPath: asset_client_path, fontCss: "", preload: [], reload: false}});
     const response = await app.request("/");
     const html = await response.text();
 
@@ -230,7 +242,7 @@ test("a missing README provides a creation hint without generated overview cards
 
     t.after(() => rm(root, {recursive: true, force: true}));
     const home = await readHome({root, processor: createProcessor({site, root})});
-    const app = createApp({site, store: {docs: [], home}, assets: {fontCss: "", preload: [], reload: false}});
+    const app = createApp({site, store: {docs: [], home}, assets: {stylePath: asset_style_path, clientPath: asset_client_path, fontCss: "", preload: [], reload: false}});
     const html = await (await app.request("/")).text();
 
     assert.equal(home, undefined);
@@ -309,7 +321,7 @@ test("headings and contents preserve authored text without automatic numbering",
     );
 
     const docs = await readDocs({root, processor: createProcessor({site, root})});
-    const app = createApp({site, store: {docs}, assets: {fontCss: "", preload: [], reload: false}});
+    const app = createApp({site, store: {docs}, assets: {stylePath: asset_style_path, clientPath: asset_client_path, fontCss: "", preload: [], reload: false}});
     const html = await (await app.request("/guide/")).text();
 
     assert.match(html, /<h2[^>]*id="overview"[^>]*><span class="wg_prose__headingText">Overview<\/span><\/h2>/);

package/src/type/site-assets.ts

@@ -2,6 +2,14 @@
  * 모든 페이지가 공유하는 HTML 머리 자원
  */
 export interface SiteAssets {
+    /**
+     * 내용 지문으로 구분한 스타일시트 URL
+     */
+    stylePath: string;
+    /**
+     * 내용 지문으로 구분한 브라우저 스크립트 URL
+     */
+    clientPath: string;
     /**
      * 내장 @font-face · head의 style 내용
      */

package/src/util/file/to-asset-path.ts

@@ -0,0 +1,26 @@
+import {createHash} from "node:crypto";
+import {readFileSync} from "node:fs";
+import {posix} from "node:path";
+
+/**
+ * 파일 내용으로 자원 URL을 구분하는 입력
+ */
+export interface AssetPathOptions {
+    /**
+     * 사이트 루트 기준 기본 자원 경로
+     */
+    path: string;
+    /**
+     * 배포할 실제 파일 경로
+     */
+    file: string;
+}
+
+/**
+ * 파일명에 내용 지문 추가 · 같은 내용은 같은 URL, 변경한 내용은 새 캐시 키 사용
+ */
+export const toAssetPath = (options: AssetPathOptions) => {
+    const extension = posix.extname(options.path);
+
+    return `${posix.dirname(options.path)}/${posix.basename(options.path, extension)}.${createHash("sha256").update(readFileSync(options.file)).digest("hex")}${extension}`;
+};