for-humanity 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## 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.
+- Add `bad` and `good` fence meta that tint the whole code block, with line notation drawn one step darker on top.
+
 ## 0.10.0 — 2026-10-13
 
 - Add VitePress-style code notation through Shiki transformers: `// [!code highlight|error|warning|++|--]`, `// [!code word:name]`, meta `{2,4-6}` and a `line-numbers` meta that numbers lines with CSS counters.

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.10.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.10.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.10.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

@@ -189,11 +189,45 @@
     background: var(--app-color-bad-soft);
     opacity: 0.8;
   }
+  & pre.wg_prose__code--bad code .line.highlighted,
+  & pre.wg_prose__code--bad code .line.highlighted.error,
+  & pre.wg_prose__code--bad code .line.diff.remove {
+    background: var(--app-color-bad-mark);
+  }
+  & pre.wg_prose__code--good code .line.highlighted,
+  & pre.wg_prose__code--good code .line.diff.add {
+    background: var(--app-color-good-mark);
+  }
   & pre code .highlighted-word {
     padding: 0 2px;
     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;
   }
@@ -779,9 +813,11 @@
   --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(#fbe9e6, #42241f);
+  --app-color-bad-soft: light-dark(#f9ebe8, #3a2522);
+  --app-color-bad-mark: light-dark(#f1cdc6, #5b322c);
   --app-color-good: light-dark(#2f7a47, #8bd3a3);
-  --app-color-good-soft: light-dark(#e3f3e8, #1f3a27);
+  --app-color-good-soft: light-dark(#e4f3ed, #1c342c);
+  --app-color-good-mark: light-dark(#c4e4d4, #27503f);
   --app-color-warn: light-dark(#8a6400, #e6c46a);
   --app-color-warn-soft: light-dark(#fbf3d9, #3d3418);
   --app-color-link: light-dark(#11a, #9db8ff);
@@ -875,6 +911,14 @@
     --app-space-gutter: 16px;
   }
 }
+.wg_prose__code--bad,
+.wg_prose__codeFile--bad {
+  --app-code-background: var(--app-color-bad-soft);
+}
+.wg_prose__code--good,
+.wg_prose__codeFile--good {
+  --app-code-background: var(--app-color-good-soft);
+}
 
 /* src/component/widget/shell/wg-shell.css */
 .wg_shell__root {

package/dist/cli.js

@@ -2,9 +2,9 @@
 
 // src/entry/cli/cli.ts
 import { EventEmitter } from "node:events";
-import { existsSync as existsSync3, readFileSync as readFileSync3, watch } from "node:fs";
+import { existsSync as existsSync4, readFileSync as readFileSync4, watch } from "node:fs";
 import { copyFile, mkdir, rm, writeFile } from "node:fs/promises";
-import { dirname as dirname4, extname as extname4, join as join4, relative as relative4, resolve as resolve3, sep as sep3 } from "node:path";
+import { dirname as dirname5, extname as extname5, join as join4, relative as relative5, resolve as resolve4, sep as sep4 } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { serve } from "@hono/node-server";
 import { serveStatic } from "@hono/node-server/serve-static";
@@ -64,6 +64,7 @@ var copy_error_directive_syntax = "\uBD80\uD488 \uBB38\uBC95\uC774 \uC62C\uBC14\
 var copy_warn_broken_link = "\uC5C6\uB294 \uBB38\uC11C\uB85C \uAC74 \uB9C1\uD06C\uB2E4";
 var copy_warn_unknown_status = "\uC124\uC815\uC5D0 \uC5C6\uB294 \uC0C1\uD0DC \uBB38\uAD6C\uB2E4";
 var copy_error_asset = "\uC790\uC6D0\uC774 \uC62C\uBC14\uB974\uC9C0 \uC54A\uB2E4";
+var copy_error_snippet = "\uCF54\uB4DC \uC2A4\uB2C8\uD3AB\uC774 \uC62C\uBC14\uB974\uC9C0 \uC54A\uB2E4";
 
 // src/constant/font.ts
 var font_mono_css = "src/asset/font/monoplex-kr/monoplex-kr.css";
@@ -1763,6 +1764,91 @@ var remarkReport = (options) => (_tree, file) => {
   }
 };
 
+// src/entry/cli/_function/create-processor/_remark-snippets.ts
+import { existsSync as existsSync3, readFileSync as readFileSync2, realpathSync as realpathSync2, statSync as statSync2 } from "node:fs";
+import { dirname as dirname3, extname as extname3, isAbsolute as isAbsolute2, relative as relative4, resolve as resolve3, sep as sep2 } from "node:path";
+import { visit as visit9 } from "unist-util-visit";
+
+// src/entry/cli/_constant/snippet.ts
+var snippet_pattern = /^<<<\s+(\S+?)(?:#([\w-]+))?(?:\s+(.+?))?\s*$/;
+var snippet_region_pattern = /^\s*\S*\s*#(end)?region\s+([\w-]+)/;
+var snippet_language_by_extension = {
+  ".cjs": "js",
+  ".md": "markdown",
+  ".mjs": "js",
+  ".mts": "ts",
+  ".txt": "text",
+  ".yml": "yaml"
+};
+
+// src/entry/cli/_function/create-processor/_remark-snippets.ts
+var toSnippetBody = (source, region) => {
+  const lines = source.replace(/\r\n/g, "\n").split("\n");
+  let inside = region === void 0;
+  let found = region === void 0;
+  const kept = [];
+  for (const line of lines) {
+    const marker = snippet_region_pattern.exec(line);
+    if (marker !== null) {
+      if (region !== void 0 && marker[2] === region) {
+        inside = marker[1] === void 0;
+        found = true;
+      }
+      continue;
+    }
+    if (inside) {
+      kept.push(line);
+    }
+  }
+  if (!found) {
+    return void 0;
+  }
+  while (kept.length > 0 && kept[0]?.trim() === "") {
+    kept.shift();
+  }
+  while (kept.length > 0 && kept.at(-1)?.trim() === "") {
+    kept.pop();
+  }
+  const indents = kept.filter((line) => line.trim() !== "").map((line) => line.length - line.trimStart().length);
+  const indent = indents.length === 0 ? 0 : Math.min(...indents);
+  return kept.map((line) => line.slice(Math.min(indent, line.length - line.trimStart().length))).join("\n");
+};
+var remarkSnippets = (options) => (tree, file) => {
+  visit9(tree, "paragraph", (node, index, parent) => {
+    const [child] = node.children;
+    if (node.children.length !== 1 || child === void 0 || child.type !== "text" || parent === void 0 || index === void 0) {
+      return;
+    }
+    const match = snippet_pattern.exec(child.value.trim());
+    if (match === null) {
+      return;
+    }
+    const [, path = "", region, meta] = match;
+    const target = resolve3(dirname3(file.path), path);
+    const location2 = relative4(options.root, target);
+    if (location2 === ".." || location2.startsWith(`..${sep2}`) || isAbsolute2(location2)) {
+      file.fail(`${copy_error_snippet}: \uBB38\uC11C \uD3F4\uB354 \uBC16 \xB7 ${path}`, node);
+    }
+    if (!existsSync3(target)) {
+      file.fail(`${copy_error_snippet}: \uD30C\uC77C\uC774 \uC5C6\uB2E4 \xB7 ${path}`, node);
+    }
+    const actual = realpathSync2(target);
+    const actualLocation = relative4(realpathSync2(options.root), actual);
+    if (actualLocation === ".." || actualLocation.startsWith(`..${sep2}`) || isAbsolute2(actualLocation) || !statSync2(actual).isFile()) {
+      file.fail(`${copy_error_snippet}: \uBB38\uC11C \uD3F4\uB354 \uBC16\uC774\uAC70\uB098 \uC77C\uBC18 \uD30C\uC77C\uC774 \uC544\uB2C8\uB2E4 \xB7 ${path}`, node);
+    }
+    const body = toSnippetBody(readFileSync2(actual, "utf8"), region);
+    if (body === void 0) {
+      file.fail(`${copy_error_snippet}: region \uC774 \uC5C6\uB2E4 \xB7 ${path}#${region}`, node);
+      return;
+    }
+    const extension = extname3(actual).toLowerCase();
+    const lang = snippet_language_by_extension[extension] === void 0 ? extension.slice(1) : snippet_language_by_extension[extension];
+    options.snippets.add(actual);
+    parent.children.splice(index, 1, { type: "code", lang, meta: meta === void 0 ? null : meta, value: body });
+  });
+};
+
 // src/entry/cli/_function/create-processor/_shiki-transformers.ts
 import {
   transformerMetaHighlight,
@@ -1780,23 +1866,66 @@ var lineNumbers = {
     }
   }
 };
+var tone = {
+  name: "for-humanity:code-tone",
+  pre(node) {
+    const meta = this.options.meta?.__raw;
+    if (typeof meta !== "string") {
+      return;
+    }
+    for (const word of ["bad", "good"]) {
+      if (new RegExp(`\\b${word}\\b`).test(meta)) {
+        this.addClassToHast(node, `wg_prose__code--${word}`);
+      }
+    }
+  }
+};
+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" }),
   transformerNotationDiff({ matchAlgorithm: "v3" }),
   transformerNotationWordHighlight({ matchAlgorithm: "v3" }),
   transformerMetaHighlight(),
-  lineNumbers
+  lineNumbers,
+  tone,
+  fileTitle
 ];
 
 // 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-" }), transformers: shikiTransformers }).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(remarkSnippets, { root: options.root, snippets: options.snippets ?? /* @__PURE__ */ new Set() }).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-" }), transformers: shikiTransformers }).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
 import { readdir, readFile as readFile2 } from "node:fs/promises";
-import { join, posix as posix3, sep as sep2 } from "node:path";
+import { join, posix as posix3, sep as sep3 } from "node:path";
 import { VFile } from "vfile";
 import { parse as parseYaml } from "yaml";
 
@@ -1845,11 +1974,11 @@ var docDataSchema = z2.object({
 // src/entry/cli/_function/read-docs.ts
 var readDocs = async (options) => {
   const paths = (await readdir(options.root, { recursive: true })).filter(
-    (path) => /\.mdx?$/i.test(path) && !/^(readme|agents|claude)\.md$/i.test(path) && !path.split(sep2).includes("node_modules") && !path.startsWith(`dist${sep2}`)
+    (path) => /\.mdx?$/i.test(path) && !/^(readme|agents|claude)\.md$/i.test(path) && !path.split(sep3).includes("node_modules") && !path.startsWith(`dist${sep3}`)
   );
   const docs = await Promise.all(
     paths.map(async (path) => {
-      const id = path.replace(/\.mdx?$/i, "").split(sep2).join("/").toLowerCase();
+      const id = path.replace(/\.mdx?$/i, "").split(sep3).join("/").toLowerCase();
       const segments = id.split("/");
       if (segments.some((segment) => segment === "" || segment === "." || segment === ".." || segment === "index.html") || /[#?%*:\\]/.test(id) || /[\p{Cc}]/u.test(id) || options.reserved?.includes(segments[0]) === true || segments[0] === asset_dir || segments[0] === asset_favicon_path.slice(1)) {
         throw new Error(`${copy_error_doc_id}: ${path}`);
@@ -2043,15 +2172,15 @@ var toErrorMessage = (error) => {
 
 // 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 dirname3, extname as extname3, join as join3 } from "node:path";
+import { readFileSync as readFileSync3 } from "node:fs";
+import { basename, dirname as dirname4, extname as extname4, join as join3 } from "node:path";
 var toFontCss = (options) => {
   const files = /* @__PURE__ */ new Map();
-  const css = [...readFileSync2(options.css, "utf8").matchAll(/@font-face\s*\{[^}]*\}/g)].map(
+  const css = [...readFileSync3(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(dirname3(options.css), relativeUrl);
-      const extension = extname3(file);
-      const hash = createHash2("sha256").update(readFileSync2(file)).digest("hex").slice(0, font_hash_length);
+      const file = join3(dirname4(options.css), relativeUrl);
+      const extension = extname4(file);
+      const hash = createHash2("sha256").update(readFileSync3(file)).digest("hex").slice(0, font_hash_length);
       const url = `${options.fontDir}/${basename(file, extension)}.${hash}${extension}`;
       files.set(url, file);
       return `url(${url})`;
@@ -2068,10 +2197,10 @@ var main = async () => {
     throw new Error(`${copy_error_unknown_command}: ${command} (${commands.join(", ")})`);
   }
   const kitRoot = fileURLToPath(new URL("../", import.meta.url));
-  const docsRoot = resolve3(docsDir);
+  const docsRoot = resolve4(docsDir);
   const outDir = join4(docsRoot, "dist");
   const configFile = join4(docsRoot, cli_config_file_name);
-  const parsedConfig = siteConfigSchema.safeParse(existsSync3(configFile) ? (await import(pathToFileURL(configFile).href)).default : site_config_absent);
+  const parsedConfig = siteConfigSchema.safeParse(existsSync4(configFile) ? (await import(pathToFileURL(configFile).href)).default : site_config_absent);
   if (!parsedConfig.success) {
     throw new Error(`${copy_error_config}: ${parsedConfig.error.issues.map((issue) => `${issue.path.join(".")} ${issue.message}`).join(", ")}`);
   }
@@ -2081,7 +2210,7 @@ var main = async () => {
     app2.use(
       "/*",
       serveStatic({
-        root: relative4(process.cwd(), outDir),
+        root: relative5(process.cwd(), outDir),
         onFound: (_path, c) => {
           if (c.req.path.startsWith(`${asset_font_dir}/`)) {
             c.header("Cache-Control", font_cache_control);
@@ -2097,7 +2226,7 @@ var main = async () => {
   const brand = toFontCss({ css: join4(kitRoot, font_brand_css), fontDir: asset_font_dir });
   const fontCss = [mono.css, body.css, brand.css].join("\n");
   const stylePath = toAssetPath({ path: asset_style_path, file: join4(kitRoot, "dist/cli.css") });
-  const browserScript = readFileSync3(join4(kitRoot, "dist/browser.js"), "utf8");
+  const browserScript = readFileSync4(join4(kitRoot, "dist/browser.js"), "utf8");
   const kitFiles = new Map([
     [stylePath, join4(kitRoot, "dist/cli.css")],
     [asset_favicon_path, join4(kitRoot, "src/asset/favicon.svg")],
@@ -2106,7 +2235,8 @@ var main = async () => {
     ...brand.files
   ]);
   const files = new Map(kitFiles);
-  const processor = createProcessor({ site: siteConfig, root: docsRoot, files });
+  const snippets = /* @__PURE__ */ new Set();
+  const processor = createProcessor({ site: siteConfig, root: docsRoot, files, snippets });
   const [docs, home] = await Promise.all([
     readDocs({ root: docsRoot, processor, reserved: siteConfig.url === void 0 ? void 0 : crawling_reserved_roots }),
     readHome({ root: docsRoot, processor })
@@ -2129,11 +2259,11 @@ var main = async () => {
       throw crawlerResult.error;
     }
     for (const [url, file] of files) {
-      await mkdir(dirname4(join4(outDir, url)), { recursive: true });
+      await mkdir(dirname5(join4(outDir, url)), { recursive: true });
       await copyFile(file, join4(outDir, url));
     }
     console.log(
-      `${crawlerResult === void 0 ? result.files.length : result.files.length + crawlerResult.files.length} files, ${files.size} assets \u2192 ${relative4(process.cwd(), outDir)}`
+      `${crawlerResult === void 0 ? result.files.length : result.files.length + crawlerResult.files.length} files, ${files.size} assets \u2192 ${relative5(process.cwd(), outDir)}`
     );
     return;
   }
@@ -2145,7 +2275,8 @@ var main = async () => {
       run: async () => {
         const currentGeneration = generation;
         const nextFiles = new Map(kitFiles);
-        const nextProcessor = createProcessor({ site: siteConfig, root: docsRoot, files: nextFiles });
+        const nextSnippets = /* @__PURE__ */ new Set();
+        const nextProcessor = createProcessor({ site: siteConfig, root: docsRoot, files: nextFiles, snippets: nextSnippets });
         const [docs2, home2] = await Promise.all([
           readDocs({ root: docsRoot, processor: nextProcessor, reserved: siteConfig.url === void 0 ? void 0 : crawling_reserved_roots }),
           readHome({ root: docsRoot, processor: nextProcessor })
@@ -2157,6 +2288,10 @@ var main = async () => {
         for (const entry of nextFiles) {
           files.set(...entry);
         }
+        snippets.clear();
+        for (const entry of nextSnippets) {
+          snippets.add(entry);
+        }
         store.docs = docs2;
         store.home = home2;
         reload.emit("change");
@@ -2167,8 +2302,9 @@ var main = async () => {
   );
   const handleDocsChange = (_event, filename) => {
     if (filename !== null) {
-      const segments = filename.split(sep3);
-      if (segments.includes("dist") || segments.includes("node_modules") || !/\.mdx?$/i.test(filename) && !asset_media_extensions.has(extname4(filename).toLowerCase())) {
+      const segments = filename.split(sep4);
+      const isSnippet = snippets.has(join4(docsRoot, filename));
+      if (segments.includes("dist") || segments.includes("node_modules") || !isSnippet && !/\.mdx?$/i.test(filename) && !asset_media_extensions.has(extname5(filename).toLowerCase())) {
         return;
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "for-humanity",
-    "version": "0.10.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

@@ -245,12 +245,54 @@
         opacity: 0.8;
     }
 
+    /* 색 블록 위의 줄 표기 · 바탕보다 한 단계 진하게 */
+    & pre.wg_prose__code--bad code .line.highlighted,
+    & pre.wg_prose__code--bad code .line.highlighted.error,
+    & pre.wg_prose__code--bad code .line.diff.remove {
+        background: var(--app-color-bad-mark);
+    }
+
+    & pre.wg_prose__code--good code .line.highlighted,
+    & pre.wg_prose__code--good code .line.diff.add {
+        background: var(--app-color-good-mark);
+    }
+
     & pre code .highlighted-word {
         padding: 0 2px;
         border-radius: var(--app-radius-inline);
         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/constant/copy.ts

@@ -126,3 +126,8 @@ export const copy_warn_unknown_status = "설정에 없는 상태 문구다";
  * 문서에서 참조한 로컬 자원의 경로·형식 오류
  */
 export const copy_error_asset = "자원이 올바르지 않다";
+
+/**
+ * `<<<` 로 불러온 코드 스니펫의 경로·파일·region 오류
+ */
+export const copy_error_snippet = "코드 스니펫이 올바르지 않다";

package/src/entry/cli/_constant/snippet.ts

@@ -0,0 +1,21 @@
+/**
+ * 스니펫 줄 · `<<< ./path.ext`, 선택 `#region`, 선택 메타(펜스 메타와 같음)
+ */
+export const snippet_pattern = /^<<<\s+(\S+?)(?:#([\w-]+))?(?:\s+(.+?))?\s*$/;
+
+/**
+ * region 표시 줄 · 주석 모양은 자유 · `#region 이름`, `#endregion 이름`
+ */
+export const snippet_region_pattern = /^\s*\S*\s*#(end)?region\s+([\w-]+)/;
+
+/**
+ * 확장자 → 펜스 언어 · 없으면 확장자 그대로
+ */
+export const snippet_language_by_extension: Record<string, string> = {
+    ".cjs": "js",
+    ".md": "markdown",
+    ".mjs": "js",
+    ".mts": "ts",
+    ".txt": "text",
+    ".yml": "yaml",
+};

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

@@ -0,0 +1,117 @@
+import {existsSync, readFileSync, realpathSync, statSync} from "node:fs";
+import {dirname, extname, isAbsolute, relative, resolve, sep} from "node:path";
+import type {Root} from "mdast";
+import {visit} from "unist-util-visit";
+import type {VFile} from "vfile";
+import {copy_error_snippet} from "@/constant/copy";
+import {snippet_language_by_extension, snippet_pattern, snippet_region_pattern} from "@/entry/cli/_constant/snippet";
+
+/**
+ * 스니펫 수집 계약
+ */
+export interface SnippetOptions {
+    /**
+     * 스니펫을 읽을 수 있는 문서 루트
+     */
+    root: string;
+    /**
+     * dev 새로고침이 지켜볼 불러온 파일 경로
+     */
+    snippets: Set<string>;
+}
+
+/**
+ * region 이름이 있으면 그 안만, 없으면 전체 · region 표시 줄은 항상 제거 · 공통 들여쓰기 제거
+ */
+const toSnippetBody = (source: string, region: string | undefined): string | undefined => {
+    const lines = source.replace(/\r\n/g, "\n").split("\n");
+    let inside = region === undefined;
+    let found = region === undefined;
+    const kept: string[] = [];
+
+    for (const line of lines) {
+        const marker = snippet_region_pattern.exec(line);
+
+        if (marker !== null) {
+            if (region !== undefined && marker[2] === region) {
+                inside = marker[1] === undefined;
+                found = true;
+            }
+
+            continue;
+        }
+
+        if (inside) {
+            kept.push(line);
+        }
+    }
+
+    if (!found) {
+        return undefined;
+    }
+
+    while (kept.length > 0 && kept[0]?.trim() === "") {
+        kept.shift();
+    }
+
+    while (kept.length > 0 && kept.at(-1)?.trim() === "") {
+        kept.pop();
+    }
+
+    const indents = kept.filter((line) => line.trim() !== "").map((line) => line.length - line.trimStart().length);
+    const indent = indents.length === 0 ? 0 : Math.min(...indents);
+
+    return kept.map((line) => line.slice(Math.min(indent, line.length - line.trimStart().length))).join("\n");
+};
+
+/**
+ * `<<< ./path.ext#region 메타` 문단 → 코드 펜스 · 파일 위치 기준 경로 · 문서 폴더 밖과 없는 파일은 빌드 실패
+ * 불러온 파일은 dev 감시 목록에 올림
+ */
+export const remarkSnippets = (options: SnippetOptions) => (tree: Root, file: VFile) => {
+    visit(tree, "paragraph", (node, index, parent) => {
+        const [child] = node.children;
+
+        if (node.children.length !== 1 || child === undefined || child.type !== "text" || parent === undefined || index === undefined) {
+            return;
+        }
+
+        const match = snippet_pattern.exec(child.value.trim());
+
+        if (match === null) {
+            return;
+        }
+
+        const [, path = "", region, meta] = match;
+        const target = resolve(dirname(file.path), path);
+        const location = relative(options.root, target);
+
+        if (location === ".." || location.startsWith(`..${sep}`) || isAbsolute(location)) {
+            file.fail(`${copy_error_snippet}: 문서 폴더 밖 · ${path}`, node);
+        }
+
+        if (!existsSync(target)) {
+            file.fail(`${copy_error_snippet}: 파일이 없다 · ${path}`, node);
+        }
+
+        const actual = realpathSync(target);
+        const actualLocation = relative(realpathSync(options.root), actual);
+
+        if (actualLocation === ".." || actualLocation.startsWith(`..${sep}`) || isAbsolute(actualLocation) || !statSync(actual).isFile()) {
+            file.fail(`${copy_error_snippet}: 문서 폴더 밖이거나 일반 파일이 아니다 · ${path}`, node);
+        }
+
+        const body = toSnippetBody(readFileSync(actual, "utf8"), region);
+
+        if (body === undefined) {
+            file.fail(`${copy_error_snippet}: region 이 없다 · ${path}#${region}`, node);
+            return;
+        }
+
+        const extension = extname(actual).toLowerCase();
+        const lang = snippet_language_by_extension[extension] === undefined ? extension.slice(1) : snippet_language_by_extension[extension];
+
+        options.snippets.add(actual);
+        parent.children.splice(index, 1, {type: "code", lang, meta: meta === undefined ? null : meta, value: body});
+    });
+};

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";
 
 /**
@@ -22,7 +23,61 @@ const lineNumbers: ShikiTransformer = {
 };
 
 /**
- * 코드 줄 표기 · `// [!code highlight|error|warning|++|--]`, `// [!code word:x]`, 메타 `{2,4-6}`, `line-numbers`
+ * 펜스 메타 `bad`·`good` → pre 에 블록 색 클래스 · 바탕색은 token.css 가 바꿈
+ */
+const tone: ShikiTransformer = {
+    name: "for-humanity:code-tone",
+    pre(node) {
+        const meta = this.options.meta?.__raw;
+
+        if (typeof meta !== "string") {
+            return;
+        }
+
+        for (const word of ["bad", "good"]) {
+            if (new RegExp(`\\b${word}\\b`).test(meta)) {
+                this.addClassToHast(node, `wg_prose__code--${word}`);
+            }
+        }
+    },
+};
+
+/**
+ * 펜스 메타 `[파일 이름]` → 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"}),
@@ -31,4 +86,6 @@ export const shikiTransformers: ShikiTransformer[] = [
     transformerNotationWordHighlight({matchAlgorithm: "v3"}),
     transformerMetaHighlight(),
     lineNumbers,
+    tone,
+    fileTitle,
 ];

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

@@ -22,19 +22,21 @@ import {remarkUnknownDirectives} from "@/component/widget/prose/_function/remark
 import {rehypeAssets} from "@/entry/cli/_function/create-processor/_rehype-assets";
 import {rehypeHeadingIds} from "@/entry/cli/_function/create-processor/_rehype-heading-ids";
 import {remarkReport} from "@/entry/cli/_function/create-processor/_remark-report";
+import {remarkSnippets} from "@/entry/cli/_function/create-processor/_remark-snippets";
 import {shikiTransformers} from "@/entry/cli/_function/create-processor/_shiki-transformers";
 import type {SiteConfig} from "@/type/site-config";
 
 /**
- * Markdown 처리 순서: remark(부품·흐름도) → 코드 강조(줄 표기 transformer) → 머리 → 제목 id → 가름 수집 → 표
+ * Markdown 처리 순서: remark(스니펫·부품·흐름도) → 코드 강조(줄 표기·블록 색 transformer) → 머리 → 제목 id → 가름 수집 → 표
  * 플러그인 HTML 조각은 마지막 rehype-raw에서 해석
  * Shiki inline style: token.css의 --app-code-* 참조
  */
-export const createProcessor = (options: {site: SiteConfig; root: string; files?: Map<string, string>}) => {
+export const createProcessor = (options: {site: SiteConfig; root: string; files?: Map<string, string>; snippets?: Set<string>}) => {
     return unified()
         .use(remarkParse)
         .use(remarkFrontmatter, ["yaml"])
         .use(remarkGfm)
+        .use(remarkSnippets, {root: options.root, snippets: options.snippets ?? new Set<string>()})
         .use(remarkSmartypants)
         .use(remarkDirective)
         .use(remarkBlocks)

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

@@ -96,6 +96,82 @@ 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-"));
+
+    try {
+        await mkdir(join(root, "snippet"));
+        await writeFile(
+            join(root, "snippet", "example.ts"),
+            "const outside = 0;\n// #region picked\n    const a = 1; // [!code error]\n    const b = 2;\n// #endregion picked\nconst after = 3;\n",
+        );
+        await writeFile(
+            join(root, "guide.md"),
+            "---\nname: Guide\nlabel: Guide\ngroup: Guide\n---\n\n## Read\n\n<<< ./snippet/example.ts#picked bad line-numbers\n\n<<< ./snippet/example.ts\n",
+        );
+        const site = siteConfigSchema.parse({});
+        const snippets = new Set<string>();
+        const [doc] = await readDocs({root, processor: createProcessor({site, root, snippets})});
+
+        assert.ok(doc);
+        assert.match(doc.html, /<pre class="[^"]*wg_prose__lineNumbers[^"]*wg_prose__code--bad[^"]*"|<pre class="[^"]*wg_prose__code--bad[^"]*wg_prose__lineNumbers[^"]*"/);
+        assert.match(doc.html, /<span class="line highlighted error">[^\n]*const<\/span>[^\n]* a/);
+        assert.equal(doc.html.includes("#region"), false, "region marker lines are removed");
+        assert.equal(doc.html.split("const</span>").length - 1, 2 + 4, "the region block has two lines and the whole-file block four");
+        assert.deepEqual(
+            [...snippets].map((entry) => entry.endsWith(join("snippet", "example.ts"))),
+            [true],
+        );
+    } finally {
+        await rm(root, {recursive: true, force: true});
+    }
+});
+
+test("code snippets reject files outside the document root, missing files and missing regions", async () => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-snippets-reject-"));
+
+    try {
+        await mkdir(join(root, "docs"));
+        await writeFile(join(root, "outside.ts"), "const x = 1;\n");
+        await writeFile(join(root, "docs", "present.ts"), "const y = 2;\n");
+        const site = siteConfigSchema.parse({});
+        const docsRoot = join(root, "docs");
+
+        for (const [reference, expected] of [
+            ["../outside.ts", /문서 폴더 밖/],
+            ["./missing.ts", /파일이 없다/],
+            ["./present.ts#nope", /region 이 없다/],
+        ] as const) {
+            await writeFile(join(docsRoot, "guide.md"), `---\nname: Guide\nlabel: Guide\ngroup: Guide\n---\n\n<<< ${reference}\n`);
+            await assert.rejects(readDocs({root: docsRoot, processor: createProcessor({site, root: docsRoot})}), expected, reference);
+        }
+    } 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/entry/cli/cli.ts

@@ -92,7 +92,8 @@ const main = async () => {
         ...brand.files,
     ]);
     const files = new Map(kitFiles);
-    const processor = createProcessor({site: siteConfig, root: docsRoot, files});
+    const snippets = new Set<string>();
+    const processor = createProcessor({site: siteConfig, root: docsRoot, files, snippets});
     const [docs, home] = await Promise.all([
         readDocs({root: docsRoot, processor, reserved: siteConfig.url === undefined ? undefined : crawling_reserved_roots}),
         readHome({root: docsRoot, processor}),
@@ -147,7 +148,8 @@ const main = async () => {
             run: async () => {
                 const currentGeneration = generation;
                 const nextFiles = new Map(kitFiles);
-                const nextProcessor = createProcessor({site: siteConfig, root: docsRoot, files: nextFiles});
+                const nextSnippets = new Set<string>();
+                const nextProcessor = createProcessor({site: siteConfig, root: docsRoot, files: nextFiles, snippets: nextSnippets});
                 const [docs, home] = await Promise.all([
                     readDocs({root: docsRoot, processor: nextProcessor, reserved: siteConfig.url === undefined ? undefined : crawling_reserved_roots}),
                     readHome({root: docsRoot, processor: nextProcessor}),
@@ -161,6 +163,10 @@ const main = async () => {
                 for (const entry of nextFiles) {
                     files.set(...entry);
                 }
+                snippets.clear();
+                for (const entry of nextSnippets) {
+                    snippets.add(entry);
+                }
                 store.docs = docs;
                 store.home = home;
                 reload.emit("change");
@@ -171,12 +177,17 @@ const main = async () => {
     );
 
     /**
-     * 입력 변경 감지 · 출력·설치 폴더 제외 · 누락 자원 추가도 다시 확인
+     * 입력 변경 감지 · 출력·설치 폴더 제외 · 누락 자원 추가도 다시 확인 · 불러온 스니펫 파일 변경 포함
      */
     const handleDocsChange = (_event: string, filename: string | null) => {
         if (filename !== null) {
             const segments = filename.split(sep);
-            if (segments.includes("dist") || segments.includes("node_modules") || (!/\.mdx?$/i.test(filename) && !asset_media_extensions.has(extname(filename).toLowerCase()))) {
+            const isSnippet = snippets.has(join(docsRoot, filename));
+            if (
+                segments.includes("dist") ||
+                segments.includes("node_modules") ||
+                (!isSnippet && !/\.mdx?$/i.test(filename) && !asset_media_extensions.has(extname(filename).toLowerCase()))
+            ) {
                 return;
             }
         }

package/src/style/token.css

@@ -35,11 +35,13 @@
     --app-color-accent: light-dark(#555, #b5b5b5);
     --app-color-accent-soft: light-dark(#f5f5f2, #222);
 
-    /* 코드 줄 표기 · error·remove 는 bad, add 는 good, warning 은 warn · soft 가 줄 바탕 */
+    /* 코드 판정 색 · soft 는 블록 바탕(메타 bad·good), mark 는 그 위의 줄 표기 · warn 은 줄 표기만 */
     --app-color-bad: light-dark(#b2412e, #ff9b8a);
-    --app-color-bad-soft: light-dark(#fbe9e6, #42241f);
+    --app-color-bad-soft: light-dark(#f9ebe8, #3a2522);
+    --app-color-bad-mark: light-dark(#f1cdc6, #5b322c);
     --app-color-good: light-dark(#2f7a47, #8bd3a3);
-    --app-color-good-soft: light-dark(#e3f3e8, #1f3a27);
+    --app-color-good-soft: light-dark(#e4f3ed, #1c342c);
+    --app-color-good-mark: light-dark(#c4e4d4, #27503f);
     --app-color-warn: light-dark(#8a6400, #e6c46a);
     --app-color-warn-soft: light-dark(#fbf3d9, #3d3418);
 
@@ -173,3 +175,14 @@
         --app-space-gutter: 16px;
     }
 }
+
+/* 블록 색 · 펜스 메타 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__codeFile--good {
+    --app-code-background: var(--app-color-good-soft);
+}