for-humanity 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 0.12.0 — 2026-10-13
+
+- Add a `[file name]` fence meta that draws a title bar with the file name and language above the code block, sharing the `bad`/`good` tone.
+
 ## 0.11.0 — 2026-10-13
 
 - Add `<<< ./file.ext#region meta` code snippet imports: a file inside the document root becomes a code block, with optional `#region` extraction, dedent, fence meta passthrough and dev reloads when the file changes.

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.11.0
+pnpm add -D --save-exact for-humanity@0.12.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.11.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.12.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.
 Set an optional public root `url` in the site configuration to generate `robots.txt` and `sitemap.xml`; projects without a URL emit neither file. See [Crawling](https://github.com/minu-ha/for-humanity/blob/main/templates/document/crawling.md).
 
@@ -75,7 +75,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.11.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.12.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

package/dist/cli.css

@@ -203,6 +203,31 @@
     border-radius: var(--app-radius-inline);
     background: var(--app-color-accent-soft);
   }
+  & .wg_prose__codeFile {
+    margin: var(--app-space-block) 0;
+  }
+  & .wg_prose__codeFile pre {
+    margin: 0;
+    border-top-left-radius: 0;
+    border-top-right-radius: 0;
+  }
+  & .wg_prose__codeFileTitle {
+    display: flex;
+    gap: var(--app-space-block);
+    justify-content: space-between;
+    padding: var(--app-space-inline) var(--app-space-block);
+    border: 1px solid var(--app-color-border);
+    border-bottom: 0;
+    border-radius: var(--app-radius-box) var(--app-radius-box) 0 0;
+    background: var(--app-code-background);
+    color: var(--app-color-text-muted);
+    font-family: var(--app-font-mono);
+    font-size: var(--app-font-size-dense);
+    letter-spacing: 0;
+  }
+  & .wg_prose__codeFileLang {
+    text-transform: uppercase;
+  }
   & pre.wg_prose__lineNumbers code {
     counter-reset: line;
   }
@@ -886,10 +911,12 @@
     --app-space-gutter: 16px;
   }
 }
-.wg_prose__code--bad {
+.wg_prose__code--bad,
+.wg_prose__codeFile--bad {
   --app-code-background: var(--app-color-bad-soft);
 }
-.wg_prose__code--good {
+.wg_prose__code--good,
+.wg_prose__codeFile--good {
   --app-code-background: var(--app-color-good-soft);
 }
 

package/dist/cli.js

@@ -1880,6 +1880,33 @@ var tone = {
     }
   }
 };
+var fileTitle = {
+  name: "for-humanity:code-title",
+  root(root) {
+    const meta = this.options.meta?.__raw;
+    const title = typeof meta === "string" ? /\[([^\]]+)\]/.exec(meta)?.[1] : void 0;
+    if (title === void 0) {
+      return;
+    }
+    const tones = typeof meta === "string" ? ["bad", "good"].filter((word) => new RegExp(`\\b${word}\\b`).test(meta)) : [];
+    const caption = {
+      type: "element",
+      tagName: "figcaption",
+      properties: { className: ["wg_prose__codeFileTitle"] },
+      children: [
+        { type: "text", value: title },
+        { type: "element", tagName: "span", properties: { className: ["wg_prose__codeFileLang"] }, children: [{ type: "text", value: this.options.lang }] }
+      ]
+    };
+    const figure = {
+      type: "element",
+      tagName: "figure",
+      properties: { className: ["wg_prose__codeFile", ...tones.map((tone2) => `wg_prose__codeFile--${tone2}`)] },
+      children: [caption, ...root.children.filter((child) => child.type !== "doctype")]
+    };
+    root.children = [figure];
+  }
+};
 var shikiTransformers = [
   transformerNotationHighlight({ matchAlgorithm: "v3" }),
   transformerNotationErrorLevel({ matchAlgorithm: "v3" }),
@@ -1887,7 +1914,8 @@ var shikiTransformers = [
   transformerNotationWordHighlight({ matchAlgorithm: "v3" }),
   transformerMetaHighlight(),
   lineNumbers,
-  tone
+  tone,
+  fileTitle
 ];
 
 // src/entry/cli/_function/create-processor/create-processor.ts

package/package.json

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

package/src/component/widget/prose/wg-prose.css

@@ -263,6 +263,36 @@
         background: var(--app-color-accent-soft);
     }
 
+    /* 파일 이름 띠 · 펜스 메타 [파일 이름] · 코드 상자와 한 몸, 여백은 figure 가 맡음 */
+    & .wg_prose__codeFile {
+        margin: var(--app-space-block) 0;
+    }
+
+    & .wg_prose__codeFile pre {
+        margin: 0;
+        border-top-left-radius: 0;
+        border-top-right-radius: 0;
+    }
+
+    & .wg_prose__codeFileTitle {
+        display: flex;
+        gap: var(--app-space-block);
+        justify-content: space-between;
+        padding: var(--app-space-inline) var(--app-space-block);
+        border: 1px solid var(--app-color-border);
+        border-bottom: 0;
+        border-radius: var(--app-radius-box) var(--app-radius-box) 0 0;
+        background: var(--app-code-background);
+        color: var(--app-color-text-muted);
+        font-family: var(--app-font-mono);
+        font-size: var(--app-font-size-dense);
+        letter-spacing: 0;
+    }
+
+    & .wg_prose__codeFileLang {
+        text-transform: uppercase;
+    }
+
     /* 줄 번호 · 펜스 메타 line-numbers · 복사에 섞이지 않게 content 로 */
     & pre.wg_prose__lineNumbers code {
         counter-reset: line;

package/src/entry/cli/_function/create-processor/_shiki-transformers.ts

@@ -5,6 +5,7 @@ import {
     transformerNotationHighlight,
     transformerNotationWordHighlight,
 } from "@shikijs/transformers";
+import type {Element, ElementContent} from "hast";
 import type {ShikiTransformer} from "shiki";
 
 /**
@@ -42,7 +43,41 @@ const tone: ShikiTransformer = {
 };
 
 /**
- * 코드 줄 표기 · `// [!code highlight|error|warning|++|--]`, `// [!code word:x]`, 메타 `{2,4-6}`, `line-numbers`, 블록 색 `bad`·`good`
+ * 펜스 메타 `[파일 이름]` → figure 로 감싸고 제목 띠에 파일 이름과 언어 · 블록 색 클래스는 figure 에도 둠
+ */
+const fileTitle: ShikiTransformer = {
+    name: "for-humanity:code-title",
+    root(root) {
+        const meta = this.options.meta?.__raw;
+        const title = typeof meta === "string" ? /\[([^\]]+)\]/.exec(meta)?.[1] : undefined;
+
+        if (title === undefined) {
+            return;
+        }
+
+        const tones = typeof meta === "string" ? ["bad", "good"].filter((word) => new RegExp(`\\b${word}\\b`).test(meta)) : [];
+        const caption: Element = {
+            type: "element",
+            tagName: "figcaption",
+            properties: {className: ["wg_prose__codeFileTitle"]},
+            children: [
+                {type: "text", value: title},
+                {type: "element", tagName: "span", properties: {className: ["wg_prose__codeFileLang"]}, children: [{type: "text", value: this.options.lang}]},
+            ],
+        };
+        const figure: Element = {
+            type: "element",
+            tagName: "figure",
+            properties: {className: ["wg_prose__codeFile", ...tones.map((tone) => `wg_prose__codeFile--${tone}`)]},
+            children: [caption, ...root.children.filter((child): child is ElementContent => child.type !== "doctype")],
+        };
+
+        root.children = [figure];
+    },
+};
+
+/**
+ * 코드 줄 표기 · `// [!code highlight|error|warning|++|--]`, `// [!code word:x]`, 메타 `{2,4-6}`, `line-numbers`, 블록 색 `bad`·`good`, 제목 `[파일 이름]`
  */
 export const shikiTransformers: ShikiTransformer[] = [
     transformerNotationHighlight({matchAlgorithm: "v3"}),
@@ -52,4 +87,5 @@ export const shikiTransformers: ShikiTransformer[] = [
     transformerMetaHighlight(),
     lineNumbers,
     tone,
+    fileTitle,
 ];

package/src/entry/cli/cli.test.ts

@@ -96,6 +96,28 @@ test("code notation marks lines, meta highlights lines, and line-numbers tags th
     }
 });
 
+test("a bracketed fence meta renders a file title bar that carries the block tone", async () => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-code-title-"));
+
+    try {
+        await writeFile(
+            join(root, "guide.md"),
+            "---\nname: Guide\nlabel: Guide\ngroup: Guide\n---\n\n## Read\n\n```ts bad [page/products.ts]\nconst a = 1;\n```\n\n```ts {1}\nconst b = 2;\n```\n",
+        );
+        const site = siteConfigSchema.parse({});
+        const [doc] = await readDocs({root, processor: createProcessor({site, root})});
+
+        assert.ok(doc);
+        assert.match(
+            doc.html,
+            /<figure class="wg_prose__codeFile wg_prose__codeFile--bad"><figcaption class="wg_prose__codeFileTitle">page\/products\.ts<span class="wg_prose__codeFileLang">ts<\/span><\/figcaption><pre class="[^"]*wg_prose__code--bad/,
+        );
+        assert.equal(doc.html.split("<figure").length - 1, 1, "braces meta is not a title");
+    } finally {
+        await rm(root, {recursive: true, force: true});
+    }
+});
+
 test("code snippets import a file or a region from inside the document root and pass fence meta", async () => {
     const root = await mkdtemp(join(tmpdir(), "for-humanity-snippets-"));
 

package/src/style/token.css

@@ -176,11 +176,13 @@
     }
 }
 
-/* 블록 색 · 펜스 메타 bad·good · Shiki 가 pre 에 인라인으로 쓰는 코드 바탕을 바꿈 */
-.wg_prose__code--bad {
+/* 블록 색 · 펜스 메타 bad·good · Shiki 가 pre 에 인라인으로 쓰는 코드 바탕과 제목 띠의 바탕을 바꿈 */
+.wg_prose__code--bad,
+.wg_prose__codeFile--bad {
     --app-code-background: var(--app-color-bad-soft);
 }
 
-.wg_prose__code--good {
+.wg_prose__code--good,
+.wg_prose__codeFile--good {
     --app-code-background: var(--app-color-good-soft);
 }