for-humanity 0.1.0

package/src/content/create-processor.ts

@@ -0,0 +1,59 @@
+import rehypeShiki from "@shikijs/rehype";
+import rehypeRaw from "rehype-raw";
+import rehypeStringify from "rehype-stringify";
+import remarkDirective from "remark-directive";
+import remarkFrontmatter from "remark-frontmatter";
+import remarkGfm from "remark-gfm";
+import remarkParse from "remark-parse";
+import remarkRehype from "remark-rehype";
+import remarkSmartypants from "remark-smartypants";
+import {createCssVariablesTheme} from "shiki";
+import {unified} from "unified";
+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 {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";
+import {remarkStatus} from "@/component/widget/prose/_function/remark-status";
+import {remarkSwatch} from "@/component/widget/prose/_function/remark-swatch";
+import {remarkUnknownDirectives} from "@/component/widget/prose/_function/remark-unknown-directives";
+import {rehypeHeadingIds} from "@/content/rehype-heading-ids";
+import {remarkReport} from "@/content/remark-report";
+import type {SiteConfig} from "@/type/site-config";
+
+/**
+ * Markdown 처리 순서: remark → 코드 강조 → 머리 → 제목 id → 가름 수집 → 표
+ * 플러그인 HTML 조각은 마지막 rehype-raw에서 해석
+ * Shiki inline style: token.css의 --app-code-* 참조
+ */
+export const createProcessor = (options: {site: SiteConfig; root: string}) => {
+    return unified()
+        .use(remarkParse)
+        .use(remarkFrontmatter, ["yaml"])
+        .use(remarkGfm)
+        .use(remarkSmartypants)
+        .use(remarkDirective)
+        .use(remarkBlocks)
+        .use(remarkParts)
+        .use(remarkFlow)
+        .use(remarkStatus, {status: options.site.status})
+        .use(remarkSwatch)
+        .use(remarkLinks, {root: options.root})
+        .use(remarkUnknownDirectives)
+        .use(remarkReport, {root: options.root})
+        .use(remarkRehype, {allowDangerousHtml: true})
+        .use(rehypeShiki, {theme: createCssVariablesTheme({name: "for-humanity", variablePrefix: "--app-code-"})})
+        .use(rehypeHead)
+        .use(rehypeHeadingIds)
+        .use(rehypeSections)
+        .use(rehypeTables)
+        .use(rehypeRaw)
+        .use(rehypeStringify, {allowDangerousHtml: true});
+};
+
+/**
+ * 플러그인 조립을 마친 Markdown 처리기
+ */
+export type Processor = ReturnType<typeof createProcessor>;

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

@@ -0,0 +1,242 @@
+import assert from "node:assert/strict";
+import {mkdir, mkdtemp, rm, writeFile} from "node:fs/promises";
+import {tmpdir} from "node:os";
+import {join} from "node:path";
+import {test} from "node:test";
+import {renderToStaticMarkup} from "react-dom/server";
+import {createApp} from "@/app";
+import {WgShellNav} from "@/component/widget/shell/_wg-shell-nav";
+import {createProcessor} from "@/content/create-processor";
+import {readDocs} from "@/content/read-docs";
+import {readHome} from "@/content/read-home";
+import {siteConfigSchema} from "@/type/site-config";
+
+test("documents with the same initial retain distinct URLs", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-docs-"));
+    const site = siteConfigSchema.parse({});
+
+    t.after(() => rm(root, {recursive: true, force: true}));
+    await Promise.all([
+        writeFile(join(root, "api.md"), "---\nname: API\nlabel: Public contracts\ngroup: Reference\n---\n\n## Overview\n\nAPI guide.\n"),
+        writeFile(join(root, "architecture.md"), "---\nname: Architecture\nlabel: Engine\ngroup: Development\n---\n\n## Overview\n\nEngine guide.\n"),
+    ]);
+
+    const docs = await readDocs({root, processor: createProcessor({site, root})});
+
+    assert.deepEqual(docs.map((doc) => doc.id).toSorted(), ["api", "architecture"]);
+    assert.deepEqual(docs.map((doc) => doc.data.name).toSorted(), ["API", "Architecture"]);
+});
+
+test("normalized document URL collisions still fail", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-docs-"));
+    const site = siteConfigSchema.parse({});
+
+    t.after(() => rm(root, {recursive: true, force: true}));
+    await Promise.all([
+        writeFile(join(root, "guide.md"), "---\nname: Guide\nlabel: Guide\ngroup: Guide\n---\n\nText.\n"),
+        writeFile(join(root, "guide.mdx"), "---\nname: Manual\nlabel: Manual\ngroup: Guide\n---\n\nText.\n"),
+    ]);
+
+    await assert.rejects(readDocs({root, processor: createProcessor({site, root})}), /문서 id가 겹친다: guide/);
+});
+
+test("navigation shows every document group in reading order without document icons", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-docs-"));
+    const site = siteConfigSchema.parse({navigation: ["Getting started", "Guide"]});
+
+    t.after(() => rm(root, {recursive: true, force: true}));
+    await Promise.all([
+        writeFile(join(root, "commands.md"), "---\nname: Commands\nlabel: Commands\ngroup: Getting started\n---\n\nText.\n"),
+        writeFile(join(root, "writing.md"), "---\nname: Writing\nlabel: Writing\ngroup: Guide\norder: 1\n---\n\nText.\n"),
+        writeFile(join(root, "parts.md"), "---\nname: Parts\nlabel: Parts\ngroup: Guide\norder: 2\n---\n\nText.\n"),
+    ]);
+
+    const docs = await readDocs({root, processor: createProcessor({site, root})});
+    const html = renderToStaticMarkup(WgShellNav({site, docs, current: "writing"}));
+    const groups = [...html.matchAll(/<section\b[^>]*aria-label="([^"]+)"/g)];
+
+    assert.deepEqual(
+        groups.map((group) => group[1]),
+        ["Getting started", "Guide"],
+    );
+    assert.doesNotMatch(html, /<details\b/);
+    assert.doesNotMatch(html, /wg_shellNav__docIcon/);
+    assert.doesNotMatch(html, /href="\/"/);
+    assert.doesNotMatch(html, />Documents<|>Overview</);
+    assert.ok(html.indexOf('href="/writing/"') < html.indexOf('href="/parts/"'));
+    assert.match(html, /href="\/writing\/"[^>]*aria-current="page"/);
+});
+
+test("frontmatter supports BOM, CRLF and a closing fence at EOF", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-docs-"));
+    const site = siteConfigSchema.parse({});
+
+    t.after(() => rm(root, {recursive: true, force: true}));
+    await Promise.all([
+        writeFile(join(root, "api.md"), "\uFEFF---\r\nname: API\r\nlabel: Public contracts\r\ngroup: Reference\r\n---\r\n\r\n예:이것\r\n"),
+        writeFile(join(root, "empty.md"), "---\nname: Empty\nlabel: Empty\ngroup: Reference\n---"),
+    ]);
+
+    const docs = await readDocs({root, processor: createProcessor({site, root})});
+
+    const api = docs.find((doc) => doc.id === "api");
+    const empty = docs.find((doc) => doc.id === "empty");
+
+    assert.ok(api);
+    assert.ok(empty);
+    assert.match(api.html, /예:이것/);
+    assert.match(empty.html, /<h1[^>]*><span[^>]*>Empty<\/span><\/h1>/);
+    assert.ok(docs.every((doc) => !doc.html.includes("wg_prose__eyebrow")));
+});
+
+test("frontmatter preserves source lines in directive errors", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-docs-"));
+    const site = siteConfigSchema.parse({});
+
+    t.after(() => rm(root, {recursive: true, force: true}));
+    await writeFile(join(root, "bad.md"), "---\nname: Broken\nlabel: Broken\ngroup: Guide\n---\n\n::unknown[Bad]\n");
+
+    await assert.rejects(readDocs({root, processor: createProcessor({site, root})}), (error: unknown) => {
+        assert.ok(error instanceof Error && "line" in error);
+        assert.equal(error.line, 7);
+
+        return true;
+    });
+});
+
+test("a plain root README renders at home and relative home links resolve from nested docs", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-home-"));
+    const site = siteConfigSchema.parse({});
+    const processor = createProcessor({site, root});
+
+    t.after(() => rm(root, {recursive: true, force: true}));
+    await mkdir(join(root, "guide"));
+    await Promise.all([
+        writeFile(
+            join(root, "readme.md"),
+            '<div align="center">\n\n<img src="/favicon.svg" width="96" height="96" alt="Library face">\n\n# My library\n\nWelcome home.\n\n</div>\n\n## Start\n\n[Guide](guide/setup.md)\n\n```js\nconst ready = true;\n```\n',
+        ),
+        writeFile(join(root, "guide/setup.md"), "---\nname: Setup\nlabel: Setup\ngroup: Guide\n---\n\n[Home](../readme.md#start)\n\n## Details\n"),
+    ]);
+
+    const [docs, home] = await Promise.all([readDocs({root, processor}), readHome({root, processor})]);
+    const app = createApp({site, store: {docs, home}, assets: {fontCss: "", preload: [], reload: false}});
+    const response = await app.request("/");
+    const html = await response.text();
+
+    assert.equal(response.status, 200);
+    assert.deepEqual(
+        docs.map((doc) => doc.id),
+        ["guide/setup"],
+    );
+    assert.match(html, /<h1[^>]*><span[^>]*>My library<\/span><\/h1>/);
+    assert.match(html, /Welcome home\./);
+    assert.match(html, /<div align="center">/);
+    assert.match(html, /src="\/favicon\.svg" width="96" height="96"/);
+    assert.match(html, /href="\/guide\/setup\/"/);
+    assert.match(html, /href="#start" data-toc-link/);
+    assert.match(html, /class="shiki/);
+    assert.match(html, /wg_shell__brand" href="\/" aria-current="page"/);
+    assert.equal([...html.matchAll(/href="\/"/g)].length, 1);
+    assert.match(docs[0].html, /href="\/#start"/);
+    assert.doesNotMatch(html, /wg_prose__eyebrow|pg_home__card/);
+    assert.equal((await app.request("/readme/")).status, 404);
+});
+
+test("a missing README provides a creation hint without generated overview cards", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-home-"));
+    const site = siteConfigSchema.parse({});
+
+    t.after(() => rm(root, {recursive: true, force: true}));
+    const home = await readHome({root, processor: createProcessor({site, root})});
+    const app = createApp({site, store: {docs: [], home}, assets: {fontCss: "", preload: [], reload: false}});
+    const html = await (await app.request("/")).text();
+
+    assert.equal(home, undefined);
+    assert.match(html, /문서 폴더에 README\.md를 추가/);
+    assert.doesNotMatch(html, /pg_home__card|>Overview<|>Documents</);
+});
+
+test("root agent instructions stay out of the rendered documents", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-instructions-"));
+    const site = siteConfigSchema.parse({});
+
+    t.after(() => rm(root, {recursive: true, force: true}));
+    await mkdir(join(root, "guide"));
+    await Promise.all([
+        writeFile(join(root, "README.md"), "# Home\n"),
+        writeFile(join(root, "AGENTS.md"), "# Agent instructions\n\nKeep commit titles concise.\n"),
+        writeFile(join(root, "claude.md"), "# Claude instructions\n\nCheck documents before committing.\n"),
+        writeFile(join(root, "guide/agents.md"), "---\nname: Agent guide\nlabel: Agent guide\ngroup: Guide\n---\n\nGuide.\n"),
+        writeFile(join(root, "guide/claude.md"), "---\nname: Claude guide\nlabel: Claude guide\ngroup: Guide\n---\n\nGuide.\n"),
+    ]);
+
+    const docs = await readDocs({root, processor: createProcessor({site, root})});
+
+    assert.deepEqual(new Set(docs.map((doc) => doc.id)), new Set(["guide/agents", "guide/claude"]));
+});
+
+test("relative Markdown links preserve query strings and fragments", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-links-"));
+    const site = siteConfigSchema.parse({});
+
+    t.after(() => rm(root, {recursive: true, force: true}));
+    await mkdir(join(root, "guide"));
+    await Promise.all([
+        writeFile(join(root, "README.md"), "# Home\n\n## Start\n"),
+        writeFile(join(root, "api.mdx"), "---\nname: API\nlabel: API\ngroup: Guide\n---\n\n## Details\n"),
+        writeFile(
+            join(root, "guide/setup.md"),
+            [
+                "---\nname: Setup\nlabel: Setup\ngroup: Guide\n---",
+                "[API](../api.mdx?mode=compact&lang=ko#details)",
+                "[Query only](../api.mdx?mode=compact)",
+                "[Home](../README.md?lang=ko#start)",
+                "[Reference][api]\n\n[api]: ../api.mdx?mode=reference#details",
+                "[Fragment](../api.mdx#details?literal=yes)",
+                "[External](https://example.com/api.md?mode=compact#details)",
+                "[Absolute](/api.md?mode=compact#details)",
+                "[Asset](diagram.svg?version=2#label)",
+                "[Local](#details?literal=yes)",
+            ].join("\n\n"),
+        ),
+    ]);
+
+    const docs = await readDocs({root, processor: createProcessor({site, root})});
+    const setup = docs.find((doc) => doc.id === "guide/setup");
+
+    assert.ok(setup);
+    assert.match(setup.html, /href="\/api\/\?mode=compact&#x26;lang=ko#details"/);
+    assert.match(setup.html, /href="\/api\/\?mode=compact"/);
+    assert.match(setup.html, /href="\/\?lang=ko#start"/);
+    assert.match(setup.html, /href="\/api\/\?mode=reference#details"/);
+    assert.match(setup.html, /href="\/api\/#details\?literal=yes"/);
+    assert.match(setup.html, /href="https:\/\/example\.com\/api\.md\?mode=compact#details"/);
+    assert.match(setup.html, /href="\/api\.md\?mode=compact#details"/);
+    assert.match(setup.html, /href="diagram\.svg\?version=2#label"/);
+    assert.match(setup.html, /href="#details\?literal=yes"/);
+});
+
+test("headings and contents preserve authored text without automatic numbering", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-headings-"));
+    const site = siteConfigSchema.parse({});
+
+    t.after(() => rm(root, {recursive: true, force: true}));
+    await writeFile(
+        join(root, "guide.md"),
+        "---\nname: Guide\nlabel: Guide\ngroup: Guide\n---\n\n### Before the first section\n\n::part[Setup]\n\n## Overview\n\n### 01. Keep this number\n\n:::details[More]\n### Nested heading\n\nBody.\n:::\n\n## Overview\n",
+    );
+
+    const docs = await readDocs({root, processor: createProcessor({site, root})});
+    const app = createApp({site, store: {docs}, assets: {fontCss: "", preload: [], reload: false}});
+    const html = await (await app.request("/guide/")).text();
+
+    assert.match(html, /<h2[^>]*id="overview"[^>]*><span class="wg_prose__headingText">Overview<\/span><\/h2>/);
+    assert.match(html, /<h3[^>]*id="01-keep-this-number"[^>]*><span class="wg_prose__headingText">01\. Keep this number<\/span><\/h3>/);
+    assert.match(html, /href="#overview"[^>]*>Overview<\/a>/);
+    assert.match(html, /href="#01-keep-this-number"[^>]*>01\. Keep this number<\/a>/);
+    assert.match(html, /href="#nested-heading"[^>]*>Nested heading<\/a>/);
+    assert.match(html, /href="#overview-1"[^>]*>Overview<\/a>/);
+    assert.match(html, /wg_shellToc__group">Setup<\/div>/);
+    assert.doesNotMatch(html, /wg_prose__num|wg_shellToc__mark/);
+});

package/src/content/read-docs.ts

@@ -0,0 +1,75 @@
+import {readdir, readFile} from "node:fs/promises";
+import {join, sep} from "node:path";
+import {VFile} from "vfile";
+import {parse as parseYaml} from "yaml";
+import {asset_dir, asset_favicon_path} from "@/constant/asset";
+import {copy_error_doc_id, copy_error_doc_id_clash, copy_error_frontmatter} from "@/constant/copy";
+import type {Processor} from "@/content/create-processor";
+import type {Doc} from "@/type/doc";
+import {docDataSchema} from "@/type/doc-data";
+import type {DocFileData} from "@/type/doc-file-data";
+
+/**
+ * Markdown 수집과 렌더링 · 루트 README는 홈, AGENTS·CLAUDE는 작성 지침으로 분리
+ * 문서 목록에서 루트 안내 파일·node_modules·dist 제외
+ * 머리말·문서 식별자 중복·플러그인 오류 시 실패
+ */
+export const readDocs = async (options: {root: string; processor: Processor}): Promise<Doc[]> => {
+    const paths = (await readdir(options.root, {recursive: true})).filter(
+        (path) => /\.mdx?$/i.test(path) && !/^(readme|agents|claude)\.md$/i.test(path) && !path.split(sep).includes("node_modules") && !path.startsWith(`dist${sep}`),
+    );
+    const docs = await Promise.all(
+        paths.map(async (path): Promise<Doc> => {
+            const id = path
+                .replace(/\.mdx?$/i, "")
+                .split(sep)
+                .join("/")
+                .toLowerCase();
+            const segments = id.split("/");
+
+            // Hono·SSG·정적 제공의 공통 URL 계약 · 예약 문자에 의한 페이지 누락 방지
+            if (
+                segments.some((segment) => segment === "" || segment === "." || segment === ".." || segment === "index.html") ||
+                /[#?%*:\\]/.test(id) ||
+                /[\p{Cc}]/u.test(id) ||
+                segments[0] === asset_dir ||
+                segments[0] === asset_favicon_path.slice(1)
+            ) {
+                throw new Error(`${copy_error_doc_id}: ${path}`);
+            }
+
+            const source = await readFile(join(options.root, path), "utf8");
+            // remark가 제외하는 UTF-8 BOM을 원문에서도 제거 · 지시문의 offset 기준 일치
+            const file = new VFile({value: source.replace(/^\uFEFF/, ""), path: join(options.root, path)});
+            const tree = options.processor.parse(file);
+            const frontmatter = tree.children[0];
+            const parsed = docDataSchema.safeParse(frontmatter?.type === "yaml" ? parseYaml(frontmatter.value) : {});
+
+            if (!parsed.success) {
+                throw new Error(`${copy_error_frontmatter}: ${path}: ${parsed.error.issues.map((issue) => `${issue.path.join(".")} ${issue.message}`).join(", ")}`);
+            }
+
+            // 플러그인의 제목·절 정보 공유
+            const fh: DocFileData = {frontmatter: parsed.data, headings: [], sections: []};
+            file.data.fh = fh;
+
+            // YAML 노드만 제외 · 본문 위치와 오류의 원본 줄·열·offset 유지
+            tree.children = tree.children.filter((node) => node.type !== "yaml");
+            const rendered = await options.processor.run(tree, file);
+
+            return {
+                id,
+                data: parsed.data,
+                html: options.processor.stringify(rendered, file),
+                outline: {headings: fh.headings, sections: fh.sections},
+            };
+        }),
+    );
+    const duplicateIds = [...Map.groupBy(docs, (doc) => doc.id)].filter((entry) => entry[1].length > 1);
+
+    if (duplicateIds.length > 0) {
+        throw new Error(`${copy_error_doc_id_clash}: ${duplicateIds.map((entry) => entry[0]).join(", ")}`);
+    }
+
+    return docs;
+};

package/src/content/read-home.ts

@@ -0,0 +1,32 @@
+import {readdir, readFile} from "node:fs/promises";
+import {join} from "node:path";
+import {VFile} from "vfile";
+import {copy_error_home_clash} from "@/constant/copy";
+import type {Processor} from "@/content/create-processor";
+import type {DocContent} from "@/type/doc-content";
+import type {DocFileData} from "@/type/doc-file-data";
+
+/**
+ * 문서 폴더의 README.md → 홈 · 대소문자 무시 · frontmatter 불필요
+ * 파일이 없으면 생성 안내 표시, 이름만 다른 README 중복은 오류
+ */
+export const readHome = async (options: {root: string; processor: Processor}): Promise<DocContent | undefined> => {
+    const paths = (await readdir(options.root)).filter((path) => path.toLowerCase() === "readme.md");
+
+    if (paths.length > 1) {
+        throw new Error(`${copy_error_home_clash}: ${paths.join(", ")}`);
+    }
+
+    if (paths.length === 0) {
+        return undefined;
+    }
+
+    const path = join(options.root, paths[0]);
+    const fh: DocFileData = {headings: [], sections: []};
+    // 파서와 지시문 원문 복원의 offset 기준을 맞추기 위해 BOM 제외
+    const file = new VFile({value: (await readFile(path, "utf8")).replace(/^\uFEFF/, ""), path, data: {fh}});
+
+    await options.processor.process(file);
+
+    return {html: String(file), outline: {headings: fh.headings, sections: fh.sections}};
+};

package/src/content/rehype-heading-ids.ts

@@ -0,0 +1,34 @@
+import Slugger from "github-slugger";
+import type {Root} from "hast";
+import {toString as toPlainText} from "hast-util-to-string";
+import {visit} from "unist-util-visit";
+import type {VFile} from "vfile";
+import type {DocHeading} from "@/type/doc-heading";
+
+/**
+ * 제목 id와 목차 수집 · 같은 제목은 -1, -2 접미사
+ * 작성한 제목 텍스트를 그대로 사용
+ */
+export const rehypeHeadingIds = () => (tree: Root, file: VFile) => {
+    const slugger = new Slugger();
+    const headings: DocHeading[] = [];
+
+    visit(tree, "element", (node) => {
+        const depth = /^h([1-6])$/.exec(node.tagName)?.[1];
+
+        if (depth === undefined) {
+            return;
+        }
+
+        const text = toPlainText(node);
+
+        node.properties.id = typeof node.properties.id === "string" ? node.properties.id : slugger.slug(text);
+        headings.push({depth: Number(depth), slug: node.properties.id, text});
+        // 텍스트 노드에는 className을 줄 수 없어 강조 영역을 분리 · 제목의 기존 줄바꿈 유지
+        node.children = [{type: "element", tagName: "span", properties: {className: ["wg_prose__headingText"]}, children: node.children}];
+    });
+
+    if (file.data.fh) {
+        file.data.fh.headings = headings;
+    }
+};

package/src/content/remark-report.ts

@@ -0,0 +1,15 @@
+import {relative} from "node:path";
+import type {Root} from "mdast";
+import type {VFile} from "vfile";
+
+/**
+ * 파일 경고의 터미널 출력 · 파일:줄 경고 · 빌드 계속
+ * 경고 수집 뒤 실행하는 마지막 remark 플러그인
+ */
+export const remarkReport = (options: {root: string}) => (_tree: Root, file: VFile) => {
+    const path = relative(options.root, file.path);
+
+    for (const message of file.messages) {
+        console.warn(`${message.line === undefined ? path : `${path}:${message.line}`} ${message.reason}`);
+    }
+};

package/src/content/to-doc-groups.ts

@@ -0,0 +1,18 @@
+import {locale_doc_group, locale_doc_name} from "@/constant/locale";
+import type {Doc} from "@/type/doc";
+import type {SiteConfig} from "@/type/site-config";
+
+/**
+ * 사이드바의 읽는 순서 · 설정 밖 묶음은 뒤에서 이름순
+ * 같은 문서 이름·순서도 파일 id로 구분해 탐색 순서를 고정
+ */
+export const toDocGroups = (options: {docs: readonly Doc[]; navigation: SiteConfig["navigation"]}) => {
+    const positions = new Map(options.navigation.map((name, index) => [name, index]));
+
+    return [...Map.groupBy(options.docs, (doc) => doc.data.group)]
+        .toSorted((a, b) => (positions.get(a[0]) ?? options.navigation.length) - (positions.get(b[0]) ?? options.navigation.length) || a[0].localeCompare(b[0], locale_doc_group))
+        .map(([name, docs]) => ({
+            name,
+            docs: docs.toSorted((a, b) => a.data.order - b.data.order || a.data.name.localeCompare(b.data.name, locale_doc_name) || a.id.localeCompare(b.id, locale_doc_name)),
+        }));
+};

package/src/dev.ts

@@ -0,0 +1,79 @@
+import type {EventEmitter} from "node:events";
+import {readFile} from "node:fs/promises";
+import {extname} from "node:path";
+import {type Context, Hono} from "hono";
+import {streamSSE} from "hono/streaming";
+import {asset_content_type_default, asset_content_types, asset_dir, asset_favicon_path, asset_reload_path} from "@/constant/asset";
+import {font_cache_control} from "@/constant/font";
+
+/**
+ * 개발 서버 입력 계약
+ */
+export interface DevOptions {
+    /**
+     * 정적 자원 외 요청을 처리할 페이지 앱
+     */
+    pages: Hono;
+    /**
+     * 자원 URL → 파일 경로 · 정적 빌드와 동일 목록
+     */
+    files: Map<string, string>;
+    /**
+     * 문서 변경 알림 · SSE 새로고침의 change 이벤트
+     */
+    reload: EventEmitter;
+}
+
+/**
+ * 개발 전용 자원·SSE 라우트 · 나머지 요청은 페이지 앱에 위임
+ * 정적 빌드의 페이지 라우트와 분리
+ */
+export const createDevApp = (options: DevOptions) => {
+    const app = new Hono();
+
+    /**
+     * 등록된 URL의 자원 응답 · 미등록 시 404
+     */
+    const handleAsset = async (c: Context) => {
+        const file = options.files.get(c.req.path);
+
+        if (file === undefined) {
+            return c.notFound();
+        }
+
+        c.header("content-type", asset_content_types[extname(file)] ?? asset_content_type_default);
+
+        if (extname(file) === ".woff2") {
+            c.header("Cache-Control", font_cache_control);
+        }
+
+        return c.body(await readFile(file));
+    };
+
+    app.get(asset_reload_path, (c) =>
+        streamSSE(
+            c,
+            (stream) =>
+                new Promise((done) => {
+                    /**
+                     * 문서 변경의 SSE 전송 · 전송 후 연결 종료
+                     */
+                    const handleChange = async () => {
+                        await stream.writeSSE({data: "change"});
+                        done();
+                    };
+
+                    options.reload.once("change", handleChange);
+                    stream.onAbort(() => {
+                        options.reload.off("change", handleChange);
+                        done();
+                    });
+                }),
+        ),
+    );
+    app.get(`/${asset_dir}/*`, handleAsset);
+    app.get(asset_favicon_path, handleAsset);
+    app.all("/*", (c) => options.pages.fetch(c.req.raw, c.env));
+
+    return app;
+};

package/src/env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="mdast-util-to-hast" />
+
+/**
+ * 컴포넌트 CSS 부수효과 import · esbuild CSS 묶음 대상
+ */
+declare module "*.css";

package/src/page/doc/pg-doc.tsx

@@ -0,0 +1,35 @@
+import {WgProse} from "@/component/widget/prose/wg-prose";
+import {WgShell} from "@/component/widget/shell/wg-shell";
+import type {Doc} from "@/type/doc";
+import type {SiteAssets} from "@/type/site-assets";
+import type {SiteConfig} from "@/type/site-config";
+
+/**
+ * /:slug/ 문서 페이지 입력 · 렌더링된 HTML 사용
+ */
+export interface PgDocProps {
+    /**
+     * 검증된 사이트 설정
+     */
+    site: SiteConfig;
+    /**
+     * 사이드바의 전체 문서
+     */
+    docs: Doc[];
+    /**
+     * HTML 머리의 공통 자원
+     */
+    assets: SiteAssets;
+    /**
+     * 현재 페이지의 문서
+     */
+    doc: Doc;
+}
+
+export const PgDoc = (props: PgDocProps) => {
+    return (
+        <WgShell site={props.site} docs={props.docs} assets={props.assets} title={props.doc.data.name} current={props.doc.id} outline={props.doc.outline}>
+            <WgProse html={props.doc.html} />
+        </WgShell>
+    );
+};

package/src/page/home/pg-home.tsx

@@ -0,0 +1,40 @@
+import {WgProse} from "@/component/widget/prose/wg-prose";
+import {WgShell} from "@/component/widget/shell/wg-shell";
+import {copy_home_missing} from "@/constant/copy";
+import type {Doc} from "@/type/doc";
+import type {DocContent} from "@/type/doc-content";
+import type {SiteAssets} from "@/type/site-assets";
+import type {SiteConfig} from "@/type/site-config";
+
+/**
+ * / 첫 화면 입력 · 문서 폴더 README의 본문과 목차
+ */
+export interface PgHomeProps {
+    /**
+     * 검증된 사이트 설정
+     */
+    site: SiteConfig;
+    /**
+     * 사이드바의 전체 문서
+     */
+    docs: Doc[];
+    /**
+     * HTML 머리의 공통 자원
+     */
+    assets: SiteAssets;
+    /**
+     * README 렌더링 결과 · 파일이 없으면 작성 안내
+     */
+    home?: DocContent;
+}
+
+export const PgHome = (props: PgHomeProps) => {
+    return (
+        <WgShell site={props.site} docs={props.docs} assets={props.assets} outline={props.home?.outline}>
+            {/**
+             * README 원문 · 없을 때만 파일 작성 안내
+             */}
+            {props.home === undefined ? <WgProse head={{title: props.site.title, lead: copy_home_missing}} /> : <WgProse html={props.home.html} />}
+        </WgShell>
+    );
+};