for-humanity 0.2.0 → 0.3.0

package/src/component/widget/shell/_wg-shell-nav-list.css

@@ -13,8 +13,30 @@
     display: block;
     padding: var(--app-space-tree-row) 0 var(--app-space-tree-row) calc(var(--app-space-tree-indent) + var(--app-space-inline));
     color: var(--app-color-text-muted);
-    font-size: var(--app-font-size-label);
+    font-size: var(--app-font-size-group);
+    line-height: calc(var(--app-font-size-dense) * var(--app-line-height-tight));
+    overflow-wrap: anywhere;
+
+    &::before {
+        position: absolute;
+        top: calc(0.5lh + var(--app-space-tree-row));
+        left: 0;
+        width: var(--app-space-tree-indent);
+        border-top: 1px solid var(--app-color-border-soft);
+        content: "";
+        pointer-events: none;
+    }
+}
+
+.wg_shellNavList__link {
+    /* 가로 가지는 링크 첫 줄 기준 · 여러 줄 제목에서도 연결 위치 유지 */
+    position: relative;
+    display: block;
+    padding: var(--app-space-tree-row) 0 var(--app-space-tree-row) calc(var(--app-space-tree-indent) + var(--app-space-inline));
+    color: var(--app-color-link);
+    font-size: var(--app-font-size-dense);
     line-height: var(--app-line-height-tight);
+    text-decoration: none;
     overflow-wrap: anywhere;
 
     &::before {
@@ -26,6 +48,33 @@
         content: "";
         pointer-events: none;
     }
+
+    &:where(:hover) {
+        text-decoration: underline;
+    }
+
+    &:where(:hover)::before {
+        border-top-color: currentcolor;
+    }
+
+    /* hover와 같은 밑줄·가지선으로 키보드 위치 표시 */
+    &:where(:focus-visible) {
+        outline: none;
+        text-decoration: underline;
+    }
+
+    &:where(:focus-visible)::before {
+        border-top-color: currentcolor;
+    }
+}
+
+.wg_shellNavList__link--active {
+    color: var(--app-color-link);
+    font-weight: var(--app-font-weight-active);
+
+    &::before {
+        border-top-color: currentcolor;
+    }
 }
 
 .wg_shellNavList__item {
@@ -62,20 +111,20 @@
     }
 
     &:where(:hover)::after {
-        border-left-color: var(--app-color-text-strong);
+        border-left-color: var(--app-color-link);
     }
 
     &:where(:has(:focus-visible))::after {
-        border-left-color: var(--app-color-text-strong);
+        border-left-color: var(--app-color-link);
     }
 
     /* 뒤 항목까지의 세로 경로 · 같은 목록의 형제 안에서만 연결 */
     &:where(:has(~ .wg_shellNavList__item:hover))::before {
-        border-left-color: var(--app-color-text-strong);
+        border-left-color: var(--app-color-link);
     }
 
     &:where(:has(~ .wg_shellNavList__item :focus-visible))::before {
-        border-left-color: var(--app-color-text-strong);
+        border-left-color: var(--app-color-link);
     }
 
     & > .wg_shellNavList__root {
@@ -84,75 +133,39 @@
 
     /* 하위 문서를 탐색할 때 조상 묶음의 가지도 함께 연결 */
     &:where(:hover) > .wg_shellNavList__branch::before {
-        border-top-color: var(--app-color-text-strong);
+        border-top-color: var(--app-color-link);
     }
 
     &:where(:has(:focus-visible)) > .wg_shellNavList__branch::before {
-        border-top-color: var(--app-color-text-strong);
+        border-top-color: var(--app-color-link);
+    }
+
+    /* 자식 문서를 탐색할 때 클릭 가능한 부모 문서의 가지도 연결 */
+    &:where(:hover) > .wg_shellNavList__link::before {
+        border-top-color: var(--app-color-link);
+    }
+
+    &:where(:has(:focus-visible)) > .wg_shellNavList__link::before {
+        border-top-color: var(--app-color-link);
     }
 }
 
 .wg_shellNavList__item--trail {
     &::before {
-        border-left-color: var(--app-color-text-strong);
+        border-left-color: var(--app-color-link);
     }
 }
 
 .wg_shellNavList__item--current {
     &::after {
-        border-left-color: var(--app-color-text-strong);
+        border-left-color: var(--app-color-link);
     }
 
     & > .wg_shellNavList__branch::before {
-        border-top-color: var(--app-color-text-strong);
-    }
-}
-
-.wg_shellNavList__link {
-    /* 가로 가지는 링크 첫 줄 기준 · 여러 줄 제목에서도 연결 위치 유지 */
-    position: relative;
-    display: block;
-    padding: var(--app-space-tree-row) 0 var(--app-space-tree-row) calc(var(--app-space-tree-indent) + var(--app-space-inline));
-    color: var(--app-color-text);
-    font-size: var(--app-font-size-dense);
-    line-height: var(--app-line-height-tight);
-    text-decoration: none;
-    overflow-wrap: anywhere;
-
-    &::before {
-        position: absolute;
-        top: calc(0.5lh + var(--app-space-tree-row));
-        left: 0;
-        width: var(--app-space-tree-indent);
-        border-top: 1px solid var(--app-color-border-soft);
-        content: "";
-        pointer-events: none;
+        border-top-color: var(--app-color-link);
     }
 
-    &:where(:hover) {
-        text-decoration: underline;
-    }
-
-    &:where(:hover)::before {
-        border-top-color: currentcolor;
-    }
-
-    /* hover와 같은 밑줄·가지선으로 키보드 위치 표시 */
-    &:where(:focus-visible) {
-        outline: none;
-        text-decoration: underline;
-    }
-
-    &:where(:focus-visible)::before {
-        border-top-color: currentcolor;
-    }
-}
-
-.wg_shellNavList__link--active {
-    color: var(--app-color-text-strong);
-    font-weight: var(--app-font-weight-active);
-
-    &::before {
-        border-top-color: currentcolor;
+    & > .wg_shellNavList__link::before {
+        border-top-color: var(--app-color-link);
     }
 }

package/src/component/widget/shell/_wg-shell-nav-list.tsx

@@ -19,8 +19,12 @@ export interface WgShellNavListProps {
 }
 
 export const WgShellNavList = (props: WgShellNavListProps) => {
+    const currentAncestors = new Set(props.currentDoc?.ancestors);
     const entries = [
-        ...props.group.docs.map((doc) => ({kind: "document" as const, key: `doc:${doc.id}`, doc, current: doc.id === props.currentDoc?.id})),
+        ...props.group.docs.map((doc) => {
+            const active = doc.id === props.currentDoc?.id;
+            return {kind: "document" as const, key: `doc:${doc.id}`, doc, active, current: active || currentAncestors.has(doc.id)};
+        }),
         ...props.group.groups.map((group) => ({
             kind: "group" as const,
             key: `group:${JSON.stringify(group.path)}`,
@@ -44,17 +48,28 @@ export const WgShellNavList = (props: WgShellNavListProps) => {
                     key={entry.key}
                 >
                     {/**
-                     * 독립 문서 · 키보드 포커스와 현재 페이지 표시는 링크가 담당
+                     * 문서 링크 · 부모도 독립 페이지, 현재 한 문서에만 페이지 상태 부여
                      */}
                     {entry.kind === "document" && (
-                        <a
-                            className={clsx("wg_shellNavList__link", {"wg_shellNavList__link--active": entry.current})}
-                            href={`/${entry.doc.id}/`}
-                            title={entry.doc.data.label}
-                            aria-current={entry.current ? "page" : undefined}
-                        >
-                            {entry.doc.data.name}
-                        </a>
+                        <Fragment>
+                            <a
+                                className={clsx("wg_shellNavList__link", {"wg_shellNavList__link--active": entry.active})}
+                                href={`/${entry.doc.id}/`}
+                                title={entry.doc.data.label}
+                                aria-current={entry.active ? "page" : undefined}
+                            >
+                                {entry.doc.data.name}
+                            </a>
+                            {/**
+                             * 하위 문서 · 부모 아래에서도 기존 목록의 들여쓰기와 키보드 이동 유지
+                             */}
+                            {entry.doc.children !== undefined && (
+                                <WgShellNavList
+                                    group={{name: entry.doc.data.name, path: entry.doc.data.group, docs: entry.doc.children, groups: []}}
+                                    currentDoc={props.currentDoc}
+                                />
+                            )}
+                        </Fragment>
                     )}
                     {/**
                      * 하위 묶음 · 같은 목록을 재귀로 이어 깊이에 따라 들여쓰기

package/src/component/widget/shell/_wg-shell-nav.css

@@ -1,5 +1,5 @@
 /*
- * 읽는 순서의 문서 목록 · 중립색 1px 트리
+ * 읽는 순서의 문서 목록 · 작은 회색 묶음과 링크색 문서
  */
 .wg_shellNav__root {
     font-size: var(--app-font-size-dense);
@@ -15,6 +15,7 @@
 .wg_shellNav__group {
     margin: 0 0 4px;
     color: var(--app-color-text-muted);
-    font-size: var(--app-font-size-label);
+    font-size: var(--app-font-size-group);
+    line-height: calc(var(--app-font-size-dense) * var(--app-line-height-tight));
     text-box: trim-start cap alphabetic;
 }

package/src/component/widget/shell/_wg-shell-toc.css

@@ -1,5 +1,5 @@
 /*
- * 문서 탐색 아래 목차 · 작성한 제목과 계층을 유지하는 중립색 트리
+ * 문서 탐색 아래 목차 · 회색 제목·묶음과 본문 글색의 이동 대상 구분
  */
 .wg_shellToc__root {
     margin-top: var(--app-space-group);
@@ -13,14 +13,15 @@
     margin-bottom: var(--app-space-inline);
     color: var(--app-color-text-muted);
     font-size: var(--app-font-size-label);
-    font-weight: var(--app-font-weight-mark);
+    font-weight: var(--app-font-weight-strong);
     letter-spacing: var(--app-letter-spacing-label);
 }
 
 .wg_shellToc__group {
     margin: var(--app-space-stack) 0 4px;
     color: var(--app-color-text-muted);
-    font-size: var(--app-font-size-label);
+    font-size: var(--app-font-size-group);
+    line-height: calc(var(--app-font-size-dense) * var(--app-line-height-tight));
 }
 
 .wg_shellToc__list {
@@ -34,7 +35,7 @@
     position: relative;
     display: block;
     padding: var(--app-space-tree-row) 0 var(--app-space-tree-row) calc(var(--app-space-tree-indent) + var(--app-space-inline));
-    color: var(--app-color-text-muted);
+    color: var(--app-color-text);
     font-size: var(--app-font-size-dense);
     line-height: var(--app-line-height-tight);
     text-decoration: none;
@@ -222,7 +223,7 @@
     position: relative;
     display: block;
     padding: var(--app-space-tree-row) 0 var(--app-space-tree-row) calc(var(--app-space-tree-indent) + var(--app-space-inline));
-    color: var(--app-color-text-muted);
+    color: var(--app-color-text);
     font-size: var(--app-font-size-detail);
     line-height: var(--app-line-height-tight);
     text-decoration: none;

package/src/component/widget/shell/wg-shell.tsx

@@ -4,7 +4,7 @@ import {toTocGroups} from "@/component/widget/shell/_function/to-toc-groups";
 import type {DocOutline} from "@/component/widget/shell/_type/doc-outline";
 import {WgShellNav} from "@/component/widget/shell/_wg-shell-nav";
 import {WgShellToc} from "@/component/widget/shell/_wg-shell-toc";
-import {asset_client_path, asset_favicon_path, asset_reload_path, asset_style_path} from "@/constant/asset";
+import {asset_favicon_path, asset_reload_path} from "@/constant/asset";
 import {copy_nav_close, copy_nav_open, copy_nav_title} from "@/constant/copy";
 import type {Doc} from "@/type/doc";
 import type {SiteAssets} from "@/type/site-assets";
@@ -71,7 +71,7 @@ export const WgShell = (props: WgShellProps) => {
                     <link key={href} rel="preload" href={href} as="font" type="font/woff2" crossOrigin="" />
                 ))}
                 <script dangerouslySetInnerHTML={{__html: 'document.documentElement.style.scrollBehavior="auto"'}} />
-                <link rel="stylesheet" href={asset_style_path} />
+                <link rel="stylesheet" href={props.assets.stylePath} />
                 {props.assets.reload && <script dangerouslySetInnerHTML={{__html: reloadScript}} />}
             </head>
             {/**
@@ -140,7 +140,7 @@ export const WgShell = (props: WgShellProps) => {
                     <div className={clsx("wg_shell__drawerContent")} data-navigation-content="" />
                 </dialog>
                 <img className={clsx("wg_shell__cursorFace")} src={asset_favicon_path} width="24" height="24" alt="" aria-hidden="true" draggable={false} data-cursor-face="" />
-                <script type="module" src={asset_client_path} />
+                <script type="module" src={props.assets.clientPath} />
             </body>
         </html>
     );

package/src/constant/asset.ts

@@ -8,12 +8,12 @@
 export const asset_dir = "_fh";
 
 /**
- * esbuild의 컴포넌트 CSS 묶음
+ * 내용 지문을 붙일 esbuild CSS의 기본 URL
  */
 export const asset_style_path = `/${asset_dir}/style.css`;
 
 /**
- * 테마·목차·hash 보정 브라우저 스크립트
+ * 내용 지문을 붙일 테마·목차·hash 보정 스크립트의 기본 URL
  */
 export const asset_client_path = `/${asset_dir}/client.js`;
 

package/src/constant/copy.ts

@@ -35,7 +35,7 @@ export const copy_home_missing = "문서 폴더에 README.md를 추가하면 이
 /**
  * 현재 문서 목차 라벨
  */
-export const copy_nav_toc_label = "Contents";
+export const copy_nav_toc_label = "On this page";
 
 /**
  * 대소문자만 다른 README 중복 오류
@@ -82,6 +82,21 @@ export const copy_error_doc_id = "문서 id에 사용할 수 없는 경로";
  */
 export const copy_error_doc_id_clash = "문서 id가 겹친다";
 
+/**
+ * 누락되거나 홈을 가리키는 부모 문서 참조
+ */
+export const copy_error_doc_parent_missing = "부모 문서가 없다";
+
+/**
+ * 자기 참조 또는 순환하는 문서 부모 경로
+ */
+export const copy_error_doc_parent_cycle = "문서 parent가 순환한다";
+
+/**
+ * 분류 경로가 다른 문서 사이의 부모 참조
+ */
+export const copy_error_doc_parent_group = "부모 문서와 group이 다르다";
+
 /**
  * 흐름도 렌더링 실패
  */

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

@@ -6,6 +6,7 @@ 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 {asset_client_path, asset_style_path} from "@/constant/asset";
 import {createProcessor} from "@/content/create-processor";
 import {readDocs} from "@/content/read-docs";
 import {readHome} from "@/content/read-home";
@@ -13,6 +14,17 @@ import {toDocGroups} from "@/content/to-doc-groups/to-doc-groups";
 import {docDataSchema} from "@/type/doc-data";
 import {siteConfigSchema} from "@/type/site-config";
 
+test("page resource URLs use the supplied content fingerprints instead of fixed cache keys", async () => {
+    const site = siteConfigSchema.parse({});
+    const assets = {fontCss: "", preload: [], reload: false, stylePath: "/_fh/style.abc123.css", clientPath: "/_fh/client.def456.js"};
+    const app = createApp({site, store: {docs: []}, assets});
+    const html = await (await app.request("/")).text();
+
+    assert.match(html, /rel="stylesheet" href="\/_fh\/style\.abc123\.css"/);
+    assert.match(html, /type="module" src="\/_fh\/client\.def456\.js"/);
+    assert.doesNotMatch(html, /(?:href|src)="\/_fh\/(?:style\.css|client\.js)"/);
+});
+
 test("documents with the same initial retain distinct URLs", async (t) => {
     const root = await mkdtemp(join(tmpdir(), "for-humanity-docs-"));
     const site = siteConfigSchema.parse({});
@@ -148,6 +160,133 @@ test("nested groups follow metadata paths and keep sibling branches and document
     assert.doesNotMatch(html, /<details\b/);
 });
 
+test("parent is an optional nonempty document ID", () => {
+    const data = {name: "Child", label: "Child", group: "Guide"};
+
+    assert.equal(docDataSchema.parse(data).parent, undefined);
+    assert.equal(docDataSchema.parse({...data, parent: " guide/settings "}).parent, "guide/settings");
+    for (const parent of ["", " ", null, 1, [], ["guide"]]) {
+        assert.equal(docDataSchema.safeParse({...data, parent}).success, false);
+    }
+});
+
+test("parent documents contain ordered descendants with independent URLs and one current page", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-parents-"));
+    const site = siteConfigSchema.parse({navigation: [["Projects", "Atlas", "Guide"]]});
+
+    t.after(() => rm(root, {recursive: true, force: true}));
+    await mkdir(join(root, "guide"));
+    await Promise.all([
+        writeFile(join(root, "settings.md"), "---\nname: Settings\nlabel: Settings\ngroup: [Projects, Atlas, Guide]\norder: 10\n---\n\nSettings introduction.\n"),
+        writeFile(join(root, "guide/site.md"), "---\nname: Site\nlabel: Site\ngroup: [Projects, Atlas, Guide]\nparent: settings\norder: 20\n---\n\nSite introduction.\n"),
+        writeFile(join(root, "themes.md"), "---\nname: Themes\nlabel: Themes\ngroup: [Projects, Atlas, Guide]\nparent: settings\norder: 10\n---\n\nThemes introduction.\n"),
+        writeFile(join(root, "details.md"), "---\nname: Details\nlabel: Details\ngroup: [Projects, Atlas, Guide]\nparent: guide/site\n---\n\nDeep child.\n"),
+        writeFile(join(root, "writing.md"), "---\nname: Writing\nlabel: Writing\ngroup: [Projects, Atlas, Guide]\norder: 20\n---\n\nIndependent guide.\n"),
+    ]);
+
+    const docs = await readDocs({root, processor: createProcessor({site, root})});
+    const groups = toDocGroups({docs, navigation: site.navigation});
+    const guide = groups[0].groups[0].groups[0];
+
+    assert.deepEqual(
+        guide.docs.map((doc) => doc.id),
+        ["settings", "writing"],
+    );
+    assert.ok(guide.docs[0].children);
+    assert.deepEqual(
+        guide.docs[0].children.map((doc) => doc.id),
+        ["themes", "guide/site"],
+    );
+    assert.ok(guide.docs[0].children[1].children);
+    assert.deepEqual(
+        guide.docs[0].children[1].children.map((doc) => doc.id),
+        ["details"],
+    );
+    assert.deepEqual(docs.find((doc) => doc.id === "details")?.ancestors, ["settings", "guide/site"]);
+    assert.deepEqual(toDocGroups({docs: docs.toReversed(), navigation: site.navigation}), groups);
+
+    const html = renderToStaticMarkup(WgShellNav({site, docs, current: "details"}));
+    assert.match(html, /href="\/settings\/"[^>]*>Settings<\/a><ul\b[^>]*aria-label="Settings"/);
+    assert.match(html, /href="\/guide\/site\/"[^>]*>Site<\/a><ul\b[^>]*aria-label="Site"/);
+    assert.match(html, /href="\/details\/"[^>]*aria-current="page"/);
+    assert.equal([...html.matchAll(/aria-current="page"/g)].length, 1);
+    assert.equal([...html.matchAll(/wg_shellNavList__link--active/g)].length, 1);
+    assert.equal([...html.matchAll(/wg_shellNavList__item--current/g)].length, 5);
+    for (const doc of docs) {
+        assert.equal(html.split(`href="/${doc.id}/"`).length - 1, 1);
+    }
+    assert.ok(html.indexOf('href="/themes/"') < html.indexOf('href="/guide/site/"'));
+    assert.doesNotMatch(renderToStaticMarkup(WgShellNav({site, docs})), /aria-current="page"|wg_shellNavList__item--current/);
+
+    const app = createApp({site, store: {docs}, assets: {stylePath: asset_style_path, clientPath: asset_client_path, fontCss: "", preload: [], reload: false}});
+    for (const doc of docs) {
+        assert.equal((await app.request(`/${doc.id}/`)).status, 200);
+    }
+});
+
+test("relative parent IDs work with both the whole collection and a project document root", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-parents-"));
+    const site = siteConfigSchema.parse({});
+    t.after(() => rm(root, {recursive: true, force: true}));
+
+    await mkdir(join(root, "project/research"), {recursive: true});
+    await mkdir(join(root, "project/guide"));
+    await Promise.all([
+        writeFile(join(root, "project/research/README.md"), "---\nname: Research\nlabel: Research\ngroup: Guide\n---\n\nResearch introduction.\n"),
+        writeFile(join(root, "project/research/parts.md"), "---\nname: Parts\nlabel: Parts\ngroup: Guide\nparent: ./readme\n---\n\nText.\n"),
+        writeFile(join(root, "project/guide/authoring.md"), "---\nname: Authoring\nlabel: Authoring\ngroup: Guide\nparent: ../research/readme\n---\n\nText.\n"),
+    ]);
+    for (const scope of [root, join(root, "project")]) {
+        const docs = await readDocs({root: scope, processor: createProcessor({site, root: scope})});
+        const parentId = scope === root ? "project/research/readme" : "research/readme";
+        const groups = toDocGroups({docs, navigation: site.navigation});
+        assert.deepEqual(
+            groups[0].docs.map((doc) => doc.id),
+            [parentId],
+        );
+        assert.ok(groups[0].docs[0].children);
+        assert.equal(groups[0].docs[0].children.length, 2);
+        assert.ok(groups[0].docs[0].children.every((doc) => doc.data.parent === parentId));
+        assert.ok(groups[0].docs[0].children.every((doc) => doc.ancestors.length === 1 && doc.ancestors[0] === parentId));
+    }
+});
+
+test("missing and home document parents fail when loading documents", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-parents-"));
+    const site = siteConfigSchema.parse({});
+    t.after(() => rm(root, {recursive: true, force: true}));
+
+    await writeFile(join(root, "README.md"), "# Home\n");
+    for (const parent of ["missing", "readme", "guide.md", "/guide/"]) {
+        await writeFile(join(root, "child.md"), `---\nname: Child\nlabel: Child\ngroup: Guide\nparent: ${parent}\n---\n\nText.\n`);
+        await assert.rejects(readDocs({root, processor: createProcessor({site, root})}), /부모 문서가 없다: child/);
+    }
+});
+
+test("self references and cycles fail when loading documents", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-parents-"));
+    const site = siteConfigSchema.parse({});
+    t.after(() => rm(root, {recursive: true, force: true}));
+
+    await writeFile(join(root, "first.md"), "---\nname: First\nlabel: First\ngroup: Guide\nparent: first\n---\n\nText.\n");
+    await assert.rejects(readDocs({root, processor: createProcessor({site, root})}), /문서 parent가 순환한다/);
+
+    await writeFile(join(root, "first.md"), "---\nname: First\nlabel: First\ngroup: Guide\nparent: second\n---\n\nText.\n");
+    await writeFile(join(root, "second.md"), "---\nname: Second\nlabel: Second\ngroup: Guide\nparent: third\n---\n\nText.\n");
+    await writeFile(join(root, "third.md"), "---\nname: Third\nlabel: Third\ngroup: Guide\nparent: first\n---\n\nText.\n");
+    await assert.rejects(readDocs({root, processor: createProcessor({site, root})}), /문서 parent가 순환한다/);
+});
+
+test("parent and child must use the same complete group path", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-parents-"));
+    const site = siteConfigSchema.parse({});
+    t.after(() => rm(root, {recursive: true, force: true}));
+
+    await writeFile(join(root, "parent.md"), "---\nname: Parent\nlabel: Parent\ngroup: [Projects, Atlas, Research]\n---\n\nText.\n");
+    await writeFile(join(root, "child.md"), "---\nname: Child\nlabel: Child\ngroup: [Projects, Beacon, Research]\nparent: parent\n---\n\nText.\n");
+    await assert.rejects(readDocs({root, processor: createProcessor({site, root})}), /부모 문서와 group이 다르다: child/);
+});
+
 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({});
@@ -201,7 +340,7 @@ test("a plain root README renders at home and relative home links resolve from 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 app = createApp({site, store: {docs, home}, assets: {stylePath: asset_style_path, clientPath: asset_client_path, fontCss: "", preload: [], reload: false}});
     const response = await app.request("/");
     const html = await response.text();
 
@@ -230,7 +369,7 @@ test("a missing README provides a creation hint without generated overview cards
 
     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 app = createApp({site, store: {docs: [], home}, assets: {stylePath: asset_style_path, clientPath: asset_client_path, fontCss: "", preload: [], reload: false}});
     const html = await (await app.request("/")).text();
 
     assert.equal(home, undefined);
@@ -309,7 +448,7 @@ test("headings and contents preserve authored text without automatic numbering",
     );
 
     const docs = await readDocs({root, processor: createProcessor({site, root})});
-    const app = createApp({site, store: {docs}, assets: {fontCss: "", preload: [], reload: false}});
+    const app = createApp({site, store: {docs}, assets: {stylePath: asset_style_path, clientPath: asset_client_path, 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>/);

package/src/content/read-docs.ts

@@ -1,9 +1,16 @@
 import {readdir, readFile} from "node:fs/promises";
-import {join, sep} from "node:path";
+import {join, posix, 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 {
+    copy_error_doc_id,
+    copy_error_doc_id_clash,
+    copy_error_doc_parent_cycle,
+    copy_error_doc_parent_group,
+    copy_error_doc_parent_missing,
+    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";
@@ -49,8 +56,14 @@ export const readDocs = async (options: {root: string; processor: Processor}): P
                 throw new Error(`${copy_error_frontmatter}: ${path}: ${parsed.error.issues.map((issue) => `${issue.path.join(".")} ${issue.message}`).join(", ")}`);
             }
 
+            // 상대 부모 id는 파일 위치 기준으로 한 번 해소 · 문서 루트를 바꿔도 같은 관계 유지
+            const data = {
+                ...parsed.data,
+                parent: parsed.data.parent !== undefined && /^\.\.?\//.test(parsed.data.parent) ? posix.join(posix.dirname(id), parsed.data.parent) : parsed.data.parent,
+            };
+
             // 플러그인의 제목·절 정보 공유
-            const fh: DocFileData = {frontmatter: parsed.data, headings: [], sections: []};
+            const fh: DocFileData = {frontmatter: data, headings: [], sections: []};
             file.data.fh = fh;
 
             // YAML 노드만 제외 · 본문 위치와 오류의 원본 줄·열·offset 유지
@@ -59,7 +72,8 @@ export const readDocs = async (options: {root: string; processor: Processor}): P
 
             return {
                 id,
-                data: parsed.data,
+                data,
+                ancestors: [],
                 html: options.processor.stringify(rendered, file),
                 outline: {headings: fh.headings, sections: fh.sections},
             };
@@ -71,5 +85,25 @@ export const readDocs = async (options: {root: string; processor: Processor}): P
         throw new Error(`${copy_error_doc_id_clash}: ${duplicateIds.map((entry) => entry[0]).join(", ")}`);
     }
 
-    return docs;
+    // 모든 파일을 수집한 뒤 부모 참조 검증 · 파일 읽기 순서와 무관한 문서 경로
+    const docsById = new Map(docs.map((doc) => [doc.id, doc]));
+    return docs.map((doc) => {
+        const ancestors = new Set([doc.id]);
+        for (let parentId = doc.data.parent; parentId !== undefined; ) {
+            const parent = docsById.get(parentId);
+            if (parent === undefined) {
+                throw new Error(`${copy_error_doc_parent_missing}: ${doc.id} → ${parentId}`);
+            }
+            if (ancestors.has(parent.id)) {
+                throw new Error(`${copy_error_doc_parent_cycle}: ${[...ancestors, parent.id].join(" → ")}`);
+            }
+            if (JSON.stringify(parent.data.group) !== JSON.stringify(doc.data.group)) {
+                throw new Error(`${copy_error_doc_parent_group}: ${doc.id} → ${parent.id}`);
+            }
+            ancestors.add(parent.id);
+            parentId = parent.data.parent;
+        }
+
+        return {...doc, ancestors: [...ancestors].slice(1).toReversed()};
+    });
 };

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

@@ -0,0 +1,15 @@
+import {locale_doc_name} from "@/constant/locale";
+import type {Doc} from "@/type/doc";
+import type {DocBranch} from "@/type/doc-branch";
+
+/**
+ * 검증된 부모 관계로 문서 가지를 재귀 구성 · 형제 순서와 URL 유지
+ */
+export const toDocBranches = (options: {docs: readonly Doc[]; children: ReadonlyMap<Doc["data"]["parent"], Doc[]>}): DocBranch[] => {
+    return options.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))
+        .map((doc) => {
+            const children = options.children.get(doc.id);
+            return {...doc, children: children === undefined ? undefined : toDocBranches({docs: children, children: options.children})};
+        });
+};