for-humanity 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 0.9.0 — 2026-10-13
+
+- Add code labels: a fence meta of `bad` or `good` with an optional title renders the code block with a colored left stripe and a caption, keeping Shiki highlighting.
+- Give table header rows a soft background and a solid rule, widen the space above sections to 44px and subsections to 28px, and set section headings to 15px so long reference pages read in blocks.
+
+## 0.8.1 — 2026-10-13
+
+- Render tab-indented code blocks at four columns per tab instead of the browser default of eight.
+
 ## 0.8.0 — 2026-10-13
 
 - Add a `cursorFace` site setting for the pixel face that follows the mouse on desktop. It is off by default; this documentation site turns it on.

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.8.0
+pnpm add -D --save-exact for-humanity@0.9.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.8.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.9.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.8.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.9.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

@@ -44,7 +44,7 @@
     border-top: 0;
   }
   & h3 {
-    margin: var(--app-space-group) 0 var(--app-space-inline);
+    margin: var(--app-space-subsection) 0 var(--app-space-inline);
     color: var(--app-color-text-strong);
     font-size: var(--app-font-size-lead);
     font-weight: var(--app-font-weight-strong);
@@ -120,6 +120,7 @@
     font-size: var(--app-font-size-detail);
     line-height: var(--app-line-height-code);
     letter-spacing: 0;
+    tab-size: 4;
   }
   & pre code {
     padding: 0;
@@ -143,7 +144,8 @@
   }
   & th {
     padding: var(--app-space-inline) var(--app-space-stack);
-    border-bottom: 1px dotted var(--app-color-border);
+    border-bottom: 1px solid var(--app-color-border);
+    background: var(--app-color-code);
     color: var(--app-color-text-strong);
     font-weight: var(--app-font-weight-strong);
     text-align: left;
@@ -167,6 +169,29 @@
     border: 0;
     border-top: 1px dotted var(--app-color-border);
   }
+  & .wg_prose__codeLabel {
+    margin: var(--app-space-block) 0;
+    border-left: 3px solid var(--app-color-bad);
+  }
+  & .wg_prose__codeLabel--good {
+    border-left-color: var(--app-color-good);
+  }
+  & .wg_prose__codeLabelTitle {
+    padding: var(--app-space-inline) var(--app-space-block);
+    background: var(--app-color-bad-soft);
+    color: var(--app-color-bad);
+    font-size: var(--app-font-size-dense);
+    font-weight: var(--app-font-weight-strong);
+  }
+  & .wg_prose__codeLabel--good .wg_prose__codeLabelTitle {
+    background: var(--app-color-good-soft);
+    color: var(--app-color-good);
+  }
+  & .wg_prose__codeLabel pre {
+    margin: 0;
+    border-left: 0;
+    border-radius: 0 var(--app-radius-box) var(--app-radius-box) 0;
+  }
 }
 .wg_prose__head {
   margin-bottom: var(--app-space-inline);
@@ -736,6 +761,10 @@
   --app-color-border-layout: light-dark(#eee, #2b2b2b);
   --app-color-accent: light-dark(#555, #b5b5b5);
   --app-color-accent-soft: light-dark(#f5f5f2, #222);
+  --app-color-bad: light-dark(#b2412e, #ff9b8a);
+  --app-color-bad-soft: light-dark(#fbeeec, #3a2522);
+  --app-color-good: light-dark(#2f7a47, #8bd3a3);
+  --app-color-good-soft: light-dark(#eaf5ee, #1f3327);
   --app-color-link: light-dark(#11a, #9db8ff);
   --app-color-link-visited: light-dark(#51a, #c5a5ed);
   --app-color-link-hover: light-dark(#44d, #c1d1ff);
@@ -755,7 +784,7 @@
   --app-font-size-body: 12px;
   --app-font-size-lead: 12px;
   --app-font-size-part: 13px;
-  --app-font-size-section: 14px;
+  --app-font-size-section: 15px;
   --app-font-size-title: 16px;
   --app-font-weight-mark: 400;
   --app-font-weight-active: 600;
@@ -774,7 +803,8 @@
   --app-space-stack: 10px;
   --app-space-block: 14px;
   --app-space-group: 20px;
-  --app-space-section: 32px;
+  --app-space-subsection: 28px;
+  --app-space-section: 44px;
   --app-space-tree-row: 0px;
   --app-space-tree-group: 16px;
   --app-space-tree-label: 2px;

package/dist/cli.js

@@ -1231,8 +1231,33 @@ var remarkBlocks = () => (tree, file) => {
   });
 };
 
-// src/component/widget/prose/_function/remark-flow.ts
+// src/component/widget/prose/_function/remark-code-labels.ts
 import { visit as visit3 } from "unist-util-visit";
+var code_label_pattern = /^(bad|good)(?:\s+(.+?))?\s*$/;
+var inserted_node_count = 3;
+var escapeHtml = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+var remarkCodeLabels = () => (tree) => {
+  visit3(tree, "code", (node, index, parent) => {
+    if (typeof node.meta !== "string" || parent === void 0 || index === void 0) {
+      return;
+    }
+    const match = code_label_pattern.exec(node.meta);
+    if (match === null) {
+      return;
+    }
+    const [, tone, title] = match;
+    const caption = title === void 0 ? "" : `<figcaption class="wg_prose__codeLabelTitle">${escapeHtml(title)}</figcaption>`;
+    node.meta = null;
+    parent.children.splice(index, 1, { type: "html", value: `<figure class="wg_prose__codeLabel wg_prose__codeLabel--${tone}">${caption}` }, node, {
+      type: "html",
+      value: "</figure>"
+    });
+    return index + inserted_node_count;
+  });
+};
+
+// src/component/widget/prose/_function/remark-flow.ts
+import { visit as visit4 } from "unist-util-visit";
 
 // src/util/mermaid/render-flow.js
 import { renderMermaidASCII } from "beautiful-mermaid";
@@ -1546,7 +1571,7 @@ var renderFlow = (source) => gridToSvg(renderMermaidASCII(widenCjk(source), ASCI
 
 // src/component/widget/prose/_function/remark-flow.ts
 var remarkFlow = () => (tree, file) => {
-  visit3(tree, "code", (node, index, parent) => {
+  visit4(tree, "code", (node, index, parent) => {
     if (node.lang !== "mermaid" || parent === void 0 || index === void 0) {
       return;
     }
@@ -1564,10 +1589,10 @@ var remarkFlow = () => (tree, file) => {
 // src/component/widget/prose/_function/remark-links.ts
 import { existsSync } from "node:fs";
 import { dirname, posix, relative, resolve } from "node:path";
-import { visit as visit4 } from "unist-util-visit";
+import { visit as visit5 } from "unist-util-visit";
 var remarkLinks = (options) => (tree, file) => {
   const here = dirname(relative(options.root, file.path));
-  visit4(tree, (node) => {
+  visit5(tree, (node) => {
     if (node.type !== "link" && node.type !== "definition") {
       return;
     }
@@ -1601,7 +1626,7 @@ var remarkParts = () => (tree) => {
 };
 
 // src/component/widget/prose/_function/remark-status.ts
-import { escape as escapeHtml, escapeRegExp } from "es-toolkit/string";
+import { escape as escapeHtml2, escapeRegExp } from "es-toolkit/string";
 import { findAndReplace } from "mdast-util-find-and-replace";
 
 // src/component/widget/prose/_constant/status.ts
@@ -1627,7 +1652,7 @@ var remarkStatus = (options) => {
           }
           return {
             type: "html",
-            value: `<span class="wg_prose__pill wg_prose__pill--${item.kind}">${escapeHtml(text)}</span>`
+            value: `<span class="wg_prose__pill wg_prose__pill--${item.kind}">${escapeHtml2(text)}</span>`
           };
         }
       ],
@@ -1651,9 +1676,9 @@ var remarkStatus = (options) => {
 };
 
 // src/component/widget/prose/_function/remark-swatch.ts
-import { visit as visit5 } from "unist-util-visit";
+import { visit as visit6 } from "unist-util-visit";
 var remarkSwatch = () => (tree) => {
-  visit5(tree, "inlineCode", (node) => {
+  visit6(tree, "inlineCode", (node) => {
     if (/^#[0-9a-f]{3,8}$/i.test(node.value.trim())) {
       node.data = {
         hProperties: { className: ["wg_prose__color"], style: `--wg-prose-chip-color: ${node.value.trim()}` }
@@ -1663,9 +1688,9 @@ var remarkSwatch = () => (tree) => {
 };
 
 // src/component/widget/prose/_function/remark-unknown-directives.ts
-import { SKIP as SKIP2, visit as visit6 } from "unist-util-visit";
+import { SKIP as SKIP2, visit as visit7 } from "unist-util-visit";
 var remarkUnknownDirectives = () => (tree, file) => {
-  visit6(tree, (node, index, parent) => {
+  visit7(tree, (node, index, parent) => {
     if (node.type === "textDirective" && parent !== void 0 && index !== void 0) {
       parent.children[index] = {
         type: "text",
@@ -1682,7 +1707,7 @@ var remarkUnknownDirectives = () => (tree, file) => {
 // src/entry/cli/_function/create-processor/_rehype-assets.ts
 import { existsSync as existsSync2, realpathSync, statSync } from "node:fs";
 import { dirname as dirname2, extname as extname2, isAbsolute, relative as relative2, resolve as resolve2, sep } from "node:path";
-import { visit as visit7 } from "unist-util-visit";
+import { visit as visit8 } from "unist-util-visit";
 
 // src/util/file/to-asset-path.ts
 import { createHash } from "node:crypto";
@@ -1695,7 +1720,7 @@ var toAssetPath = (options) => {
 
 // src/entry/cli/_function/create-processor/_rehype-assets.ts
 var rehypeAssets = (options) => (tree, file) => {
-  visit7(tree, "element", (node) => {
+  visit8(tree, "element", (node) => {
     const property = node.tagName === "img" ? "src" : "href";
     const url = node.properties[property];
     if (node.tagName !== "img" && node.tagName !== "a" || typeof url !== "string" || /^(?:[a-z][a-z\d+.-]*:|\/|#)/i.test(url)) {
@@ -1735,11 +1760,11 @@ var rehypeAssets = (options) => (tree, file) => {
 // src/entry/cli/_function/create-processor/_rehype-heading-ids.ts
 import Slugger from "github-slugger";
 import { toString as toPlainText3 } from "hast-util-to-string";
-import { visit as visit8 } from "unist-util-visit";
+import { visit as visit9 } from "unist-util-visit";
 var rehypeHeadingIds = () => (tree, file) => {
   const slugger = new Slugger();
   const headings = [];
-  visit8(tree, "element", (node) => {
+  visit9(tree, "element", (node) => {
     const depth = /^h([1-6])$/.exec(node.tagName)?.[1];
     if (depth === void 0) {
       return;
@@ -1765,7 +1790,7 @@ var remarkReport = (options) => (_tree, file) => {
 
 // src/entry/cli/_function/create-processor/create-processor.ts
 var createProcessor = (options) => {
-  return unified().use(remarkParse).use(remarkFrontmatter, ["yaml"]).use(remarkGfm).use(remarkSmartypants).use(remarkDirective).use(remarkBlocks).use(remarkParts).use(remarkFlow).use(remarkStatus, { status: options.site.status }).use(remarkSwatch).use(remarkLinks, { root: options.root }).use(remarkUnknownDirectives).use(remarkReport, { root: options.root }).use(remarkRehype, { allowDangerousHtml: true }).use(rehypeShiki, { theme: createCssVariablesTheme({ name: "for-humanity", variablePrefix: "--app-code-" }) }).use(rehypeHead).use(rehypeHeadingIds).use(rehypeSections).use(rehypeTables).use(rehypeRaw).use(rehypeAssets, { root: options.root, files: options.files ?? /* @__PURE__ */ new Map() }).use(rehypeStringify, { allowDangerousHtml: true });
+  return unified().use(remarkParse).use(remarkFrontmatter, ["yaml"]).use(remarkGfm).use(remarkSmartypants).use(remarkDirective).use(remarkBlocks).use(remarkParts).use(remarkFlow).use(remarkCodeLabels).use(remarkStatus, { status: options.site.status }).use(remarkSwatch).use(remarkLinks, { root: options.root }).use(remarkUnknownDirectives).use(remarkReport, { root: options.root }).use(remarkRehype, { allowDangerousHtml: true }).use(rehypeShiki, { theme: createCssVariablesTheme({ name: "for-humanity", variablePrefix: "--app-code-" }) }).use(rehypeHead).use(rehypeHeadingIds).use(rehypeSections).use(rehypeTables).use(rehypeRaw).use(rehypeAssets, { root: options.root, files: options.files ?? /* @__PURE__ */ new Map() }).use(rehypeStringify, { allowDangerousHtml: true });
 };
 
 // src/entry/cli/_function/read-docs.ts

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "for-humanity",
-    "version": "0.8.0",
+    "version": "0.9.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/_function/remark-code-labels.ts

@@ -0,0 +1,47 @@
+import type {Root} from "mdast";
+import {visit} from "unist-util-visit";
+
+/**
+ * 펜스 메타의 라벨 · `bad 제목`, `good 제목` · 제목은 선택
+ */
+const code_label_pattern = /^(bad|good)(?:\s+(.+?))?\s*$/;
+
+/**
+ * figure 여는 조각, 코드, 닫는 조각
+ */
+const inserted_node_count = 3;
+
+/**
+ * 제목을 HTML 문자열에 넣기 위한 escape
+ */
+const escapeHtml = (text: string) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+
+/**
+ * 코드 펜스 메타 `bad`·`good` → 색 띠와 제목이 붙은 figure · 다른 메타는 그대로 둠
+ * 코드 노드는 유지해 Shiki 강조를 받고, figure 조각은 마지막 rehype-raw에서 합쳐짐
+ */
+export const remarkCodeLabels = () => (tree: Root) => {
+    visit(tree, "code", (node, index, parent) => {
+        if (typeof node.meta !== "string" || parent === undefined || index === undefined) {
+            return;
+        }
+
+        const match = code_label_pattern.exec(node.meta);
+
+        if (match === null) {
+            return;
+        }
+
+        const [, tone, title] = match;
+        const caption = title === undefined ? "" : `<figcaption class="wg_prose__codeLabelTitle">${escapeHtml(title)}</figcaption>`;
+
+        node.meta = null;
+        parent.children.splice(index, 1, {type: "html", value: `<figure class="wg_prose__codeLabel wg_prose__codeLabel--${tone}">${caption}`}, node, {
+            type: "html",
+            value: "</figure>",
+        });
+
+        // 끼워 넣은 세 노드 다음부터 계속
+        return index + inserted_node_count;
+    });
+};

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

@@ -60,7 +60,7 @@
     }
 
     & h3 {
-        margin: var(--app-space-group) 0 var(--app-space-inline);
+        margin: var(--app-space-subsection) 0 var(--app-space-inline);
         color: var(--app-color-text-strong);
         font-size: var(--app-font-size-lead);
         font-weight: var(--app-font-weight-strong);
@@ -153,6 +153,9 @@
         font-size: var(--app-font-size-detail);
         line-height: var(--app-line-height-code);
         letter-spacing: 0;
+
+        /* 탭 들여쓰기 코드 · 브라우저 기본 8칸은 좁은 본문에서 너무 넓음 */
+        tab-size: 4;
     }
 
     & pre code {
@@ -182,7 +185,8 @@
 
     & th {
         padding: var(--app-space-inline) var(--app-space-stack);
-        border-bottom: 1px dotted var(--app-color-border);
+        border-bottom: 1px solid var(--app-color-border);
+        background: var(--app-color-code);
         color: var(--app-color-text-strong);
         font-weight: var(--app-font-weight-strong);
         text-align: left;
@@ -211,6 +215,35 @@
         border: 0;
         border-top: 1px dotted var(--app-color-border);
     }
+
+    /* 라벨 코드 · 왼쪽 띠와 제목 · 코드 상자의 여백은 figure 가 맡음 · 토큰은 token.css 의 bad·good */
+    & .wg_prose__codeLabel {
+        margin: var(--app-space-block) 0;
+        border-left: 3px solid var(--app-color-bad);
+    }
+
+    & .wg_prose__codeLabel--good {
+        border-left-color: var(--app-color-good);
+    }
+
+    & .wg_prose__codeLabelTitle {
+        padding: var(--app-space-inline) var(--app-space-block);
+        background: var(--app-color-bad-soft);
+        color: var(--app-color-bad);
+        font-size: var(--app-font-size-dense);
+        font-weight: var(--app-font-weight-strong);
+    }
+
+    & .wg_prose__codeLabel--good .wg_prose__codeLabelTitle {
+        background: var(--app-color-good-soft);
+        color: var(--app-color-good);
+    }
+
+    & .wg_prose__codeLabel pre {
+        margin: 0;
+        border-left: 0;
+        border-radius: 0 var(--app-radius-box) var(--app-radius-box) 0;
+    }
     /* stylelint-enable selector-disallowed-list */
 }
 

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

@@ -13,6 +13,7 @@ import {rehypeHead} from "@/component/widget/prose/_function/rehype-head";
 import {rehypeSections} from "@/component/widget/prose/_function/rehype-sections/rehype-sections";
 import {rehypeTables} from "@/component/widget/prose/_function/rehype-tables";
 import {remarkBlocks} from "@/component/widget/prose/_function/remark-blocks";
+import {remarkCodeLabels} from "@/component/widget/prose/_function/remark-code-labels";
 import {remarkFlow} from "@/component/widget/prose/_function/remark-flow";
 import {remarkLinks} from "@/component/widget/prose/_function/remark-links";
 import {remarkParts} from "@/component/widget/prose/_function/remark-parts";
@@ -25,7 +26,7 @@ import {remarkReport} from "@/entry/cli/_function/create-processor/_remark-repor
 import type {SiteConfig} from "@/type/site-config";
 
 /**
- * Markdown 처리 순서: remark → 코드 강조 → 머리 → 제목 id → 가름 수집 → 표
+ * Markdown 처리 순서: remark(부품·흐름도·코드 라벨) → 코드 강조 → 머리 → 제목 id → 가름 수집 → 표
  * 플러그인 HTML 조각은 마지막 rehype-raw에서 해석
  * Shiki inline style: token.css의 --app-code-* 참조
  */
@@ -39,6 +40,7 @@ export const createProcessor = (options: {site: SiteConfig; root: string; files?
         .use(remarkBlocks)
         .use(remarkParts)
         .use(remarkFlow)
+        .use(remarkCodeLabels)
         .use(remarkStatus, {status: options.site.status})
         .use(remarkSwatch)
         .use(remarkLinks, {root: options.root})

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

@@ -73,6 +73,30 @@ test("site port defaults to 4321 and accepts only integers in the TCP range", ()
     }
 });
 
+test("code fences labelled bad or good render a captioned figure and keep highlighting", async () => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-code-labels-"));
+
+    try {
+        await writeFile(
+            join(root, "guide.md"),
+            "---\nname: Guide\nlabel: Guide\ngroup: Guide\n---\n\n## Read\n\n```ts bad 리터럴 <폴백>\nconst a = 1;\n```\n\n```ts good\nconst b = 2;\n```\n\n```ts other meta\nconst c = 3;\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__codeLabel wg_prose__codeLabel--bad"><figcaption class="wg_prose__codeLabelTitle">리터럴 &#x3C;폴백><\/figcaption>\s*<pre class="shiki/,
+        );
+        assert.match(doc.html, /<figure class="wg_prose__codeLabel wg_prose__codeLabel--good">\s*<pre class="shiki/);
+        assert.equal(doc.html.split("<figure").length - 1, 2, "other meta stays a plain code block");
+        assert.equal(doc.html.split("</figure>").length - 1, 2);
+    } finally {
+        await rm(root, {recursive: true, force: true});
+    }
+});
+
 test("cursor face is off unless the site turns it on", () => {
     assert.equal(siteConfigSchema.parse({}).cursorFace, false);
     assert.equal(siteConfigSchema.parse({cursorFace: true}).cursorFace, true);

package/src/style/token.css

@@ -35,6 +35,12 @@
     --app-color-accent: light-dark(#555, #b5b5b5);
     --app-color-accent-soft: light-dark(#f5f5f2, #222);
 
+    /* 라벨 코드 · bad·good 띠와 제목 · soft 제목 바탕 */
+    --app-color-bad: light-dark(#b2412e, #ff9b8a);
+    --app-color-bad-soft: light-dark(#fbeeec, #3a2522);
+    --app-color-good: light-dark(#2f7a47, #8bd3a3);
+    --app-color-good-soft: light-dark(#eaf5ee, #1f3327);
+
     /* 링크 · 기본·방문·hover */
     --app-color-link: light-dark(#11a, #9db8ff);
     --app-color-link-visited: light-dark(#51a, #c5a5ed);
@@ -63,7 +69,7 @@
     --app-font-size-body: 12px;
     --app-font-size-lead: 12px;
     --app-font-size-part: 13px;
-    --app-font-size-section: 14px;
+    --app-font-size-section: 15px;
     --app-font-size-title: 16px;
 
     /* 굵기 · 기본 400 · 현재 위치·제목·강조 600 */
@@ -90,7 +96,8 @@
     --app-space-stack: 10px;
     --app-space-block: 14px;
     --app-space-group: 20px;
-    --app-space-section: 32px;
+    --app-space-subsection: 28px;
+    --app-space-section: 44px;
 
     /* 탐색 트리 · 항목 위아래 여백·묶음 사이·묶음 라벨 아래·중첩 들여쓰기 */
     --app-space-tree-row: 0px;