for-humanity 0.9.1 → 0.11.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 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.
+- Remove the `bad`/`good` code labels added in 0.9.0; mark the lines instead.
+- Draw tables and flowchart boxes with the same border color as code blocks.
+
 ## 0.9.1 — 2026-10-13
 
 - Draw tables with an outer border and cell borders, box flowcharts with a border, and separate sections with a solid rule and 64px of space.

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.9.1
+pnpm add -D --save-exact for-humanity@0.11.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.9.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.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).
 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.9.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.11.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

@@ -138,15 +138,14 @@
   }
   & table {
     width: 100%;
-    border: 1px solid var(--app-color-border-soft);
+    border: 1px solid var(--app-color-border);
     border-collapse: collapse;
     font-size: var(--app-font-size-dense);
     font-variant-numeric: tabular-nums;
   }
   & th {
     padding: var(--app-space-inline) var(--app-space-stack);
-    border: 1px solid var(--app-color-border-soft);
-    border-bottom-color: var(--app-color-border);
+    border: 1px solid var(--app-color-border);
     background: var(--app-color-code);
     color: var(--app-color-text-strong);
     font-weight: var(--app-font-weight-strong);
@@ -156,7 +155,7 @@
   }
   & td {
     padding: var(--app-space-inline) var(--app-space-stack);
-    border: 1px solid var(--app-color-border-soft);
+    border: 1px solid var(--app-color-border);
     text-align: left;
     vertical-align: top;
   }
@@ -168,28 +167,54 @@
     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);
+  & pre code .line {
+    display: inline-block;
+    width: calc(100% + 2 * var(--app-space-block));
+    margin: 0 calc(-1 * var(--app-space-block));
+    padding: 0 var(--app-space-block);
   }
-  & .wg_prose__codeLabel--good {
-    border-left-color: var(--app-color-good);
+  & pre code .line.highlighted {
+    background: var(--app-color-accent-soft);
   }
-  & .wg_prose__codeLabelTitle {
-    padding: var(--app-space-inline) var(--app-space-block);
+  & pre code .line.highlighted.error {
     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 {
+  & pre code .line.highlighted.warning {
+    background: var(--app-color-warn-soft);
+  }
+  & pre code .line.diff.add {
     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;
+  & pre code .line.diff.remove {
+    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);
+  }
+  & pre.wg_prose__lineNumbers code {
+    counter-reset: line;
+  }
+  & pre.wg_prose__lineNumbers code .line::before {
+    display: inline-block;
+    width: 2em;
+    margin-right: var(--app-space-stack);
+    color: var(--app-color-text-muted);
+    text-align: right;
+    content: counter(line);
+    counter-increment: line;
+    user-select: none;
   }
 }
 .wg_prose__head {
@@ -272,7 +297,7 @@
   overflow-x: auto;
   margin: var(--app-space-block) 0;
   padding: var(--app-space-block);
-  border: 1px solid var(--app-color-border-soft);
+  border: 1px solid var(--app-color-border);
   border-radius: var(--app-radius-box);
   letter-spacing: 0;
   & svg {
@@ -763,9 +788,13 @@
   --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-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(#eaf5ee, #1f3327);
+  --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);
   --app-color-link-visited: light-dark(#51a, #c5a5ed);
   --app-color-link-hover: light-dark(#44d, #c1d1ff);
@@ -857,10 +886,10 @@
     --app-space-gutter: 16px;
   }
 }
-.wg_prose__codeLabel--bad {
+.wg_prose__code--bad {
   --app-code-background: var(--app-color-bad-soft);
 }
-.wg_prose__codeLabel--good {
+.wg_prose__code--good {
   --app-code-background: var(--app-color-good-soft);
 }
 

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";
@@ -1231,33 +1232,8 @@ var remarkBlocks = () => (tree, file) => {
   });
 };
 
-// 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";
+import { visit as visit3 } from "unist-util-visit";
 
 // src/util/mermaid/render-flow.js
 import { renderMermaidASCII } from "beautiful-mermaid";
@@ -1571,7 +1547,7 @@ var renderFlow = (source) => gridToSvg(renderMermaidASCII(widenCjk(source), ASCI
 
 // src/component/widget/prose/_function/remark-flow.ts
 var remarkFlow = () => (tree, file) => {
-  visit4(tree, "code", (node, index, parent) => {
+  visit3(tree, "code", (node, index, parent) => {
     if (node.lang !== "mermaid" || parent === void 0 || index === void 0) {
       return;
     }
@@ -1589,10 +1565,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 visit5 } from "unist-util-visit";
+import { visit as visit4 } from "unist-util-visit";
 var remarkLinks = (options) => (tree, file) => {
   const here = dirname(relative(options.root, file.path));
-  visit5(tree, (node) => {
+  visit4(tree, (node) => {
     if (node.type !== "link" && node.type !== "definition") {
       return;
     }
@@ -1626,7 +1602,7 @@ var remarkParts = () => (tree) => {
 };
 
 // src/component/widget/prose/_function/remark-status.ts
-import { escape as escapeHtml2, escapeRegExp } from "es-toolkit/string";
+import { escape as escapeHtml, escapeRegExp } from "es-toolkit/string";
 import { findAndReplace } from "mdast-util-find-and-replace";
 
 // src/component/widget/prose/_constant/status.ts
@@ -1652,7 +1628,7 @@ var remarkStatus = (options) => {
           }
           return {
             type: "html",
-            value: `<span class="wg_prose__pill wg_prose__pill--${item.kind}">${escapeHtml2(text)}</span>`
+            value: `<span class="wg_prose__pill wg_prose__pill--${item.kind}">${escapeHtml(text)}</span>`
           };
         }
       ],
@@ -1676,9 +1652,9 @@ var remarkStatus = (options) => {
 };
 
 // src/component/widget/prose/_function/remark-swatch.ts
-import { visit as visit6 } from "unist-util-visit";
+import { visit as visit5 } from "unist-util-visit";
 var remarkSwatch = () => (tree) => {
-  visit6(tree, "inlineCode", (node) => {
+  visit5(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()}` }
@@ -1688,9 +1664,9 @@ var remarkSwatch = () => (tree) => {
 };
 
 // src/component/widget/prose/_function/remark-unknown-directives.ts
-import { SKIP as SKIP2, visit as visit7 } from "unist-util-visit";
+import { SKIP as SKIP2, visit as visit6 } from "unist-util-visit";
 var remarkUnknownDirectives = () => (tree, file) => {
-  visit7(tree, (node, index, parent) => {
+  visit6(tree, (node, index, parent) => {
     if (node.type === "textDirective" && parent !== void 0 && index !== void 0) {
       parent.children[index] = {
         type: "text",
@@ -1707,7 +1683,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 visit8 } from "unist-util-visit";
+import { visit as visit7 } from "unist-util-visit";
 
 // src/util/file/to-asset-path.ts
 import { createHash } from "node:crypto";
@@ -1720,7 +1696,7 @@ var toAssetPath = (options) => {
 
 // src/entry/cli/_function/create-processor/_rehype-assets.ts
 var rehypeAssets = (options) => (tree, file) => {
-  visit8(tree, "element", (node) => {
+  visit7(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)) {
@@ -1760,11 +1736,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 visit9 } from "unist-util-visit";
+import { visit as visit8 } from "unist-util-visit";
 var rehypeHeadingIds = () => (tree, file) => {
   const slugger = new Slugger();
   const headings = [];
-  visit9(tree, "element", (node) => {
+  visit8(tree, "element", (node) => {
     const depth = /^h([1-6])$/.exec(node.tagName)?.[1];
     if (depth === void 0) {
       return;
@@ -1788,14 +1764,140 @@ 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,
+  transformerNotationDiff,
+  transformerNotationErrorLevel,
+  transformerNotationHighlight,
+  transformerNotationWordHighlight
+} from "@shikijs/transformers";
+var lineNumbers = {
+  name: "for-humanity:line-numbers",
+  pre(node) {
+    const meta = this.options.meta?.__raw;
+    if (typeof meta === "string" && /\bline-numbers\b/.test(meta)) {
+      this.addClassToHast(node, "wg_prose__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 shikiTransformers = [
+  transformerNotationHighlight({ matchAlgorithm: "v3" }),
+  transformerNotationErrorLevel({ matchAlgorithm: "v3" }),
+  transformerNotationDiff({ matchAlgorithm: "v3" }),
+  transformerNotationWordHighlight({ matchAlgorithm: "v3" }),
+  transformerMetaHighlight(),
+  lineNumbers,
+  tone
+];
+
 // 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(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 });
+  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";
 
@@ -1844,11 +1946,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}`);
@@ -2042,15 +2144,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})`;
@@ -2067,10 +2169,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(", ")}`);
   }
@@ -2080,7 +2182,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);
@@ -2096,7 +2198,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")],
@@ -2105,7 +2207,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 })
@@ -2128,11 +2231,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;
   }
@@ -2144,7 +2247,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 })
@@ -2156,6 +2260,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");
@@ -2166,8 +2274,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.9.1",
+    "version": "0.11.0",
     "description": "Documents written for humans to read: a docs kit with a sidebar, parts, sections and flowcharts, built on Hono JSX",
     "keywords": [
         "docs",
@@ -51,6 +51,7 @@
     "dependencies": {
         "@hono/node-server": "^2.1.3",
         "@shikijs/rehype": "^4.4.3",
+        "@shikijs/transformers": "4.4.3",
         "beautiful-mermaid": "^1.1.3",
         "clsx": "^2.1.1",
         "es-toolkit": "^1.52.0",

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

@@ -176,10 +176,10 @@
         margin-bottom: 0;
     }
 
-    /* 표 · 코드 상자처럼 바깥 선과 칸 선 · 머리 행은 바탕과 진한 밑선 */
+    /* 표 · 코드 상자와 같은 선 색으로 바깥 선과 칸 선 · 머리 행은 바탕 */
     & table {
         width: 100%;
-        border: 1px solid var(--app-color-border-soft);
+        border: 1px solid var(--app-color-border);
         border-collapse: collapse;
         font-size: var(--app-font-size-dense);
         font-variant-numeric: tabular-nums;
@@ -187,8 +187,7 @@
 
     & th {
         padding: var(--app-space-inline) var(--app-space-stack);
-        border: 1px solid var(--app-color-border-soft);
-        border-bottom-color: var(--app-color-border);
+        border: 1px solid var(--app-color-border);
         background: var(--app-color-code);
         color: var(--app-color-text-strong);
         font-weight: var(--app-font-weight-strong);
@@ -199,7 +198,7 @@
 
     & td {
         padding: var(--app-space-inline) var(--app-space-stack);
-        border: 1px solid var(--app-color-border-soft);
+        border: 1px solid var(--app-color-border);
         text-align: left;
         vertical-align: top;
     }
@@ -215,34 +214,71 @@
         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);
+    /* stylelint-disable selector-class-pattern -- Shiki 가 만드는 line·highlighted·diff 클래스 */
+
+    /* 코드 줄 · 바탕을 상자 가로 전체로 · 표기 없는 줄은 보이는 차이 없음 */
+    & pre code .line {
+        display: inline-block;
+        width: calc(100% + 2 * var(--app-space-block));
+        margin: 0 calc(-1 * var(--app-space-block));
+        padding: 0 var(--app-space-block);
     }
 
-    & .wg_prose__codeLabel--good {
-        border-left-color: var(--app-color-good);
+    & pre code .line.highlighted {
+        background: var(--app-color-accent-soft);
     }
 
-    & .wg_prose__codeLabelTitle {
-        padding: var(--app-space-inline) var(--app-space-block);
+    & pre code .line.highlighted.error {
         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 {
+    & pre code .line.highlighted.warning {
+        background: var(--app-color-warn-soft);
+    }
+
+    & pre code .line.diff.add {
         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;
+    & pre code .line.diff.remove {
+        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);
+    }
+
+    /* 줄 번호 · 펜스 메타 line-numbers · 복사에 섞이지 않게 content 로 */
+    & pre.wg_prose__lineNumbers code {
+        counter-reset: line;
+    }
+
+    & pre.wg_prose__lineNumbers code .line::before {
+        display: inline-block;
+        width: 2em;
+        margin-right: var(--app-space-stack);
+        color: var(--app-color-text-muted);
+        text-align: right;
+        content: counter(line);
+        counter-increment: line;
+        user-select: none;
     }
+    /* stylelint-enable selector-class-pattern */
     /* stylelint-enable selector-disallowed-list */
 }
 
@@ -354,7 +390,7 @@
     overflow-x: auto;
     margin: var(--app-space-block) 0;
     padding: var(--app-space-block);
-    border: 1px solid var(--app-color-border-soft);
+    border: 1px solid var(--app-color-border);
     border-radius: var(--app-radius-box);
 
     /* 라벨 위치는 자간 0의 격자로 계산 */

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

@@ -0,0 +1,55 @@
+import {
+    transformerMetaHighlight,
+    transformerNotationDiff,
+    transformerNotationErrorLevel,
+    transformerNotationHighlight,
+    transformerNotationWordHighlight,
+} from "@shikijs/transformers";
+import type {ShikiTransformer} from "shiki";
+
+/**
+ * 펜스 메타에 `line-numbers` 가 있으면 pre 에 줄 번호 클래스 · 번호는 CSS counter
+ */
+const lineNumbers: ShikiTransformer = {
+    name: "for-humanity:line-numbers",
+    pre(node) {
+        const meta = this.options.meta?.__raw;
+
+        if (typeof meta === "string" && /\bline-numbers\b/.test(meta)) {
+            this.addClassToHast(node, "wg_prose__lineNumbers");
+        }
+    },
+};
+
+/**
+ * 펜스 메타 `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}`);
+            }
+        }
+    },
+};
+
+/**
+ * 코드 줄 표기 · `// [!code highlight|error|warning|++|--]`, `// [!code word:x]`, 메타 `{2,4-6}`, `line-numbers`, 블록 색 `bad`·`good`
+ */
+export const shikiTransformers: ShikiTransformer[] = [
+    transformerNotationHighlight({matchAlgorithm: "v3"}),
+    transformerNotationErrorLevel({matchAlgorithm: "v3"}),
+    transformerNotationDiff({matchAlgorithm: "v3"}),
+    transformerNotationWordHighlight({matchAlgorithm: "v3"}),
+    transformerMetaHighlight(),
+    lineNumbers,
+    tone,
+];

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

@@ -13,7 +13,6 @@ 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";
@@ -23,31 +22,33 @@ 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(부품·흐름도·코드 라벨) → 코드 강조 → 머리 → 제목 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)
         .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(rehypeShiki, {theme: createCssVariablesTheme({name: "for-humanity", variablePrefix: "--app-code-"}), transformers: shikiTransformers})
         .use(rehypeHead)
         .use(rehypeHeadingIds)
         .use(rehypeSections)

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

@@ -73,25 +73,78 @@ 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-"));
+test("code notation marks lines, meta highlights lines, and line-numbers tags the block", async () => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-code-notation-"));
 
     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",
+            "---\nname: Guide\nlabel: Guide\ngroup: Guide\n---\n\n## Read\n\n```ts line-numbers\nconst a = 1; // [!code error]\nconst b = 2; // [!code ++]\nconst c = 3;\n```\n\n```txt\n# [!code highlight]\nfirst\nsecond\n```\n\n```css {2}\n.a {\n  color: red;\n}\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, /<pre class="[^"]*wg_prose__lineNumbers[^"]*"/);
+        assert.match(doc.html, /<span class="line highlighted error">/);
+        assert.match(doc.html, /<span class="line diff add">/);
+        assert.match(doc.html, /<span class="line highlighted">[^\n]*first/);
+        assert.equal(doc.html.includes("[!code"), false, "notation comments are removed from the output");
+        assert.equal(doc.html.split('<span class="line highlighted">').length - 1, 2, "a standalone txt notation line and the css {2} meta each highlight one line");
+    } 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],
         );
-        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("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});
     }

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,15 @@
     --app-color-accent: light-dark(#555, #b5b5b5);
     --app-color-accent-soft: light-dark(#f5f5f2, #222);
 
-    /* 라벨 코드 · bad·good 띠와 제목 · soft 제목 바탕 */
+    /* 코드 판정 색 · soft 는 블록 바탕(메타 bad·good), mark 는 그 위의 줄 표기 · warn 은 줄 표기만 */
     --app-color-bad: light-dark(#b2412e, #ff9b8a);
-    --app-color-bad-soft: light-dark(#fbeeec, #3a2522);
+    --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(#eaf5ee, #1f3327);
+    --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);
 
     /* 링크 · 기본·방문·hover */
     --app-color-link: light-dark(#11a, #9db8ff);
@@ -172,11 +176,11 @@
     }
 }
 
-/* 라벨 코드 · Shiki 가 pre 에 인라인으로 쓰는 코드 바탕을 figure 색으로 바꿈 */
-.wg_prose__codeLabel--bad {
+/* 블록 색 · 펜스 메타 bad·good · Shiki 가 pre 에 인라인으로 쓰는 코드 바탕을 바꿈 */
+.wg_prose__code--bad {
     --app-code-background: var(--app-color-bad-soft);
 }
 
-.wg_prose__codeLabel--good {
+.wg_prose__code--good {
     --app-code-background: var(--app-color-good-soft);
 }

package/src/component/widget/prose/_function/remark-code-labels.ts

@@ -1,47 +0,0 @@
-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;
-    });
-};