for-humanity 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## Unreleased
+
+## 0.3.0 — 2026-10-04
+
+- Support nested document pages with optional `parent` IDs, preserving existing groups and document URLs.
+- Resolve `./` and `../` parent references relative to document files so project folders can also be used as document roots.
+- Reject missing parents, self references, parent cycles and parent links across different group paths.
+- Extend active, hover and keyboard focus tree paths through clickable parent documents.
+- Distinguish sidebar groups from document links and page headings, and rename the table of contents to "On this page" with a gray label matching the groups.
+- Clarify trunk-based development, site deployment and package release policy.
+
 ## 0.2.1 — 2026-10-04
 
 - Fingerprint stylesheet and browser-script URLs so new pages cannot reuse assets cached from an older deployment.

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.2.1
+pnpm add -D --save-exact for-humanity@0.3.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.2.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.3.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.
 
 ### Develop the kit
@@ -74,7 +74,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.2.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.3.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
@@ -95,6 +95,7 @@ export default {
 See [Commands](https://github.com/minu-ha/for-humanity/blob/main/templates/document/commands.md) for using another document folder, and [Settings](https://github.com/minu-ha/for-humanity/blob/main/templates/document/settings.md) for configuration.
 Each document other than the root README chooses a `group` and optional `order`. Pages stay independent; groups do not need parent documents or nested folders. Document names may share the same first letter.
 Use `group: Guide` for one group or `group: [Projects, Example project, Research]` for nested navigation. Group paths do not change document URLs.
+Use `parent: writing` to place a document below another document in the same group. File-relative references such as `parent: ./readme` also work. Parent pages remain clickable and each page keeps its own URL; see [Navigation](https://github.com/minu-ha/for-humanity/blob/main/templates/document/navigation.md).
 
 ## Write with context
 

package/dist/cli.css

@@ -306,8 +306,27 @@
   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 {
     position: absolute;
@@ -318,6 +337,26 @@
     content: "";
     pointer-events: none;
   }
+  &:where(:hover) {
+    text-decoration: underline;
+  }
+  &:where(:hover)::before {
+    border-top-color: currentcolor;
+  }
+  &: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 {
   display: flow-root;
@@ -345,77 +384,47 @@
     pointer-events: none;
   }
   &: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 {
     margin-left: var(--app-space-tree-indent);
   }
   &: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;
-  }
-  &:where(:hover) {
-    text-decoration: underline;
+    border-top-color: var(--app-color-link);
   }
-  &:where(:hover)::before {
-    border-top-color: currentcolor;
-  }
-  &: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);
   }
 }
 
@@ -432,7 +441,8 @@
 .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;
 }
 
@@ -448,13 +458,14 @@
   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 {
   margin: 0 0 0 var(--app-space-tree-inset);
@@ -465,7 +476,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;
@@ -611,7 +622,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;
@@ -702,6 +713,7 @@
     sans-serif;
   --app-font-mono: "JetBrains Mono Variable", var(--app-font-sans);
   --app-font-brand: "Architects Daughter", var(--app-font-sans);
+  --app-font-size-group: 11px;
   --app-font-size-label: 12px;
   --app-font-size-detail: 12px;
   --app-font-size-dense: 12px;
@@ -711,7 +723,7 @@
   --app-font-size-section: 14px;
   --app-font-size-title: 16px;
   --app-font-weight-mark: 400;
-  --app-font-weight-active: 500;
+  --app-font-weight-active: 600;
   --app-font-weight-strong: 600;
   --app-font-weight-title: 600;
   --app-line-height-title: 1.5;

package/dist/cli.js

@@ -73,8 +73,12 @@ import clsx2 from "clsx";
 import { Fragment } from "react";
 import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
 var WgShellNavList = (props) => {
+  const currentAncestors = new Set(props.currentDoc?.ancestors);
   const entries = [
-    ...props.group.docs.map((doc) => ({ kind: "document", 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", key: `doc:${doc.id}`, doc, active, current: active || currentAncestors.has(doc.id) };
+    }),
     ...props.group.groups.map((group) => ({
       kind: "group",
       key: `group:${JSON.stringify(group.path)}`,
@@ -91,16 +95,25 @@ var WgShellNavList = (props) => {
         "wg_shellNavList__item--current": entry.current
       }),
       children: [
-        entry.kind === "document" && /* @__PURE__ */ jsx2(
-          "a",
-          {
-            className: clsx2("wg_shellNavList__link", { "wg_shellNavList__link--active": entry.current }),
-            href: `/${entry.doc.id}/`,
-            title: entry.doc.data.label,
-            "aria-current": entry.current ? "page" : void 0,
-            children: entry.doc.data.name
-          }
-        ),
+        entry.kind === "document" && /* @__PURE__ */ jsxs2(Fragment, { children: [
+          /* @__PURE__ */ jsx2(
+            "a",
+            {
+              className: clsx2("wg_shellNavList__link", { "wg_shellNavList__link--active": entry.active }),
+              href: `/${entry.doc.id}/`,
+              title: entry.doc.data.label,
+              "aria-current": entry.active ? "page" : void 0,
+              children: entry.doc.data.name
+            }
+          ),
+          entry.doc.children !== void 0 && /* @__PURE__ */ jsx2(
+            WgShellNavList,
+            {
+              group: { name: entry.doc.data.name, path: entry.doc.data.group, docs: entry.doc.children, groups: [] },
+              currentDoc: props.currentDoc
+            }
+          )
+        ] }),
         entry.kind === "group" && /* @__PURE__ */ jsxs2(Fragment, { children: [
           /* @__PURE__ */ jsx2("span", { className: clsx2("wg_shellNavList__branch"), children: entry.group.name }),
           /* @__PURE__ */ jsx2(WgShellNavList, { group: entry.group, currentDoc: props.currentDoc })
@@ -118,7 +131,7 @@ var copy_nav_open = "Open navigation";
 var copy_nav_close = "Close navigation";
 var copy_nav_title = "Navigation";
 var copy_home_missing = "\uBB38\uC11C \uD3F4\uB354\uC5D0 README.md\uB97C \uCD94\uAC00\uD558\uBA74 \uC774\uACF3\uC5D0 \uD648 \uD654\uBA74\uC73C\uB85C \uD45C\uC2DC\uB429\uB2C8\uB2E4.";
-var copy_nav_toc_label = "Contents";
+var copy_nav_toc_label = "On this page";
 var copy_error_home_clash = "\uD648 README\uAC00 \uACB9\uCE5C\uB2E4";
 var copy_error_prefix = "for-humanity";
 var copy_error_font_preload = "Missing bundled font for preload";
@@ -128,6 +141,9 @@ var copy_error_frontmatter = "frontmatter\uAC00 \uC62C\uBC14\uB974\uC9C0 \uC54A\
 var copy_error_navigation_clash = "navigation\uC758 \uBB36\uC74C\uC774 \uACB9\uCE5C\uB2E4";
 var copy_error_doc_id = "\uBB38\uC11C id\uC5D0 \uC0AC\uC6A9\uD560 \uC218 \uC5C6\uB294 \uACBD\uB85C";
 var copy_error_doc_id_clash = "\uBB38\uC11C id\uAC00 \uACB9\uCE5C\uB2E4";
+var copy_error_doc_parent_missing = "\uBD80\uBAA8 \uBB38\uC11C\uAC00 \uC5C6\uB2E4";
+var copy_error_doc_parent_cycle = "\uBB38\uC11C parent\uAC00 \uC21C\uD658\uD55C\uB2E4";
+var copy_error_doc_parent_group = "\uBD80\uBAA8 \uBB38\uC11C\uC640 group\uC774 \uB2E4\uB974\uB2E4";
 var copy_error_flow = "\uD750\uB984\uB3C4\uB97C \uADF8\uB9AC\uC9C0 \uBABB\uD588\uB2E4";
 var copy_error_unknown_directive = "\uBAA8\uB974\uB294 \uBD80\uD488\uC774\uB2E4";
 var copy_error_directive_syntax = "\uBD80\uD488 \uBB38\uBC95\uC774 \uC62C\uBC14\uB974\uC9C0 \uC54A\uB2E4";
@@ -138,6 +154,14 @@ var copy_warn_unknown_status = "\uC124\uC815\uC5D0 \uC5C6\uB294 \uC0C1\uD0DC \uB
 var locale_doc_name = "en";
 var locale_doc_group = "ko";
 
+// src/content/to-doc-groups/_to-doc-branches.ts
+var toDocBranches = (options) => {
+  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 === void 0 ? void 0 : toDocBranches({ docs: children, children: options.children }) };
+  });
+};
+
 // src/content/to-doc-groups/_to-doc-group-branches.ts
 var toDocGroupBranches = (options) => {
   return [
@@ -157,8 +181,17 @@ var toDocGroupBranches = (options) => {
     return {
       name: group.name,
       path: group.path,
-      docs: group.docs.filter((doc) => doc.data.group.length === group.path.length).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)),
-      groups: toDocGroupBranches({ docs: group.docs, path: group.path, positions: options.positions, unlistedPosition: options.unlistedPosition })
+      docs: toDocBranches({
+        docs: group.docs.filter((doc) => doc.data.group.length === group.path.length && doc.data.parent === void 0),
+        children: options.children
+      }),
+      groups: toDocGroupBranches({
+        docs: group.docs,
+        children: options.children,
+        path: group.path,
+        positions: options.positions,
+        unlistedPosition: options.unlistedPosition
+      })
     };
   });
 };
@@ -166,7 +199,8 @@ var toDocGroupBranches = (options) => {
 // src/content/to-doc-groups/to-doc-groups.ts
 var toDocGroups = (options) => {
   const positions = new Map(options.navigation.flatMap((path, index) => path.map((_name, depth) => [JSON.stringify(path.slice(0, depth + 1)), index])).toReversed());
-  return toDocGroupBranches({ docs: options.docs, path: [], positions, unlistedPosition: options.navigation.length });
+  const children = Map.groupBy(options.docs, (doc) => doc.data.parent);
+  return toDocGroupBranches({ docs: options.docs, children, path: [], positions, unlistedPosition: options.navigation.length });
 };
 
 // src/component/widget/shell/_wg-shell-nav.tsx
@@ -972,7 +1006,7 @@ var createProcessor = (options) => {
 
 // src/content/read-docs.ts
 import { readdir, readFile } from "node:fs/promises";
-import { join, sep } from "node:path";
+import { join, posix as posix2, sep } from "node:path";
 import { VFile } from "vfile";
 import { parse as parseYaml } from "yaml";
 
@@ -1008,6 +1042,10 @@ var docDataSchema = z2.object({
    * 사이드바의 문서 묶음 경로 · 문자열도 배열로 정규화
    */
   group: groupPathSchema,
+  /**
+   * 같은 묶음 안의 부모 문서 id · 확장자 제외, ./·../ 상대 경로도 허용
+   */
+  parent: z2.string().trim().min(1).optional(),
   /**
    * 묶음 안의 읽는 순서 · 미지정 문서는 뒤에서 이름순
    */
@@ -1034,13 +1072,18 @@ var readDocs = async (options) => {
       if (!parsed.success) {
         throw new Error(`${copy_error_frontmatter}: ${path}: ${parsed.error.issues.map((issue) => `${issue.path.join(".")} ${issue.message}`).join(", ")}`);
       }
-      const fh = { frontmatter: parsed.data, headings: [], sections: [] };
+      const data = {
+        ...parsed.data,
+        parent: parsed.data.parent !== void 0 && /^\.\.?\//.test(parsed.data.parent) ? posix2.join(posix2.dirname(id), parsed.data.parent) : parsed.data.parent
+      };
+      const fh = { frontmatter: data, headings: [], sections: [] };
       file.data.fh = fh;
       tree.children = tree.children.filter((node) => node.type !== "yaml");
       const rendered = await options.processor.run(tree, file);
       return {
         id,
-        data: parsed.data,
+        data,
+        ancestors: [],
         html: options.processor.stringify(rendered, file),
         outline: { headings: fh.headings, sections: fh.sections }
       };
@@ -1050,7 +1093,25 @@ var readDocs = async (options) => {
   if (duplicateIds.length > 0) {
     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 = /* @__PURE__ */ new Set([doc.id]);
+    for (let parentId = doc.data.parent; parentId !== void 0; ) {
+      const parent = docsById.get(parentId);
+      if (parent === void 0) {
+        throw new Error(`${copy_error_doc_parent_missing}: ${doc.id} \u2192 ${parentId}`);
+      }
+      if (ancestors.has(parent.id)) {
+        throw new Error(`${copy_error_doc_parent_cycle}: ${[...ancestors, parent.id].join(" \u2192 ")}`);
+      }
+      if (JSON.stringify(parent.data.group) !== JSON.stringify(doc.data.group)) {
+        throw new Error(`${copy_error_doc_parent_group}: ${doc.id} \u2192 ${parent.id}`);
+      }
+      ancestors.add(parent.id);
+      parentId = parent.data.parent;
+    }
+    return { ...doc, ancestors: [...ancestors].slice(1).toReversed() };
+  });
 };
 
 // src/content/read-home.ts
@@ -1172,10 +1233,10 @@ var toErrorMessage = (error) => {
 // src/util/file/to-asset-path.ts
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
-import { posix as posix2 } from "node:path";
+import { posix as posix3 } from "node:path";
 var toAssetPath = (options) => {
-  const extension = posix2.extname(options.path);
-  return `${posix2.dirname(options.path)}/${posix2.basename(options.path, extension)}.${createHash("sha256").update(readFileSync(options.file)).digest("hex")}${extension}`;
+  const extension = posix3.extname(options.path);
+  return `${posix3.dirname(options.path)}/${posix3.basename(options.path, extension)}.${createHash("sha256").update(readFileSync(options.file)).digest("hex")}${extension}`;
 };
 
 // src/util/font/to-font-css.ts

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "for-humanity",
-    "version": "0.2.1",
+    "version": "0.3.0",
     "description": "Documents written for humans to read: a docs kit with a sidebar, parts, sections and flowcharts, built on Hono and React",
     "keywords": [
         "docs",

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/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

@@ -160,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({});

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})};
+        });
+};

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

@@ -1,4 +1,5 @@
-import {locale_doc_group, locale_doc_name} from "@/constant/locale";
+import {locale_doc_group} from "@/constant/locale";
+import {toDocBranches} from "@/content/to-doc-groups/_to-doc-branches";
 import type {Doc} from "@/type/doc";
 import type {DocGroup} from "@/type/doc-group";
 
@@ -10,6 +11,10 @@ interface DocGroupBranchesOptions {
      * 부모 경로에 속한 문서
      */
     docs: readonly Doc[];
+    /**
+     * 검증된 부모 id별 문서 · 자손을 각 단계에서 다시 수집하지 않음
+     */
+    children: ReadonlyMap<Doc["data"]["parent"], Doc[]>;
     /**
      * 부모까지의 경로 · 최상위는 빈 배열
      */
@@ -49,10 +54,17 @@ export const toDocGroupBranches = (options: DocGroupBranchesOptions): DocGroup[]
             return {
                 name: group.name,
                 path: group.path,
-                docs: group.docs
-                    .filter((doc) => doc.data.group.length === group.path.length)
-                    .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)),
-                groups: toDocGroupBranches({docs: group.docs, path: group.path, positions: options.positions, unlistedPosition: options.unlistedPosition}),
+                docs: toDocBranches({
+                    docs: group.docs.filter((doc) => doc.data.group.length === group.path.length && doc.data.parent === undefined),
+                    children: options.children,
+                }),
+                groups: toDocGroupBranches({
+                    docs: group.docs,
+                    children: options.children,
+                    path: group.path,
+                    positions: options.positions,
+                    unlistedPosition: options.unlistedPosition,
+                }),
             };
         });
 };

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

@@ -10,5 +10,6 @@ export const toDocGroups = (options: {docs: readonly Doc[]; navigation: SiteConf
     // 같은 조상을 지정한 경로는 최초 navigation 위치를 우선
     const positions = new Map(options.navigation.flatMap((path, index) => path.map((_name, depth) => [JSON.stringify(path.slice(0, depth + 1)), index] as const)).toReversed());
 
-    return toDocGroupBranches({docs: options.docs, path: [], positions, unlistedPosition: options.navigation.length});
+    const children = Map.groupBy(options.docs, (doc) => doc.data.parent);
+    return toDocGroupBranches({docs: options.docs, children, path: [], positions, unlistedPosition: options.navigation.length});
 };

package/src/style/token.css

@@ -55,7 +55,8 @@
     --app-font-mono: "JetBrains Mono Variable", var(--app-font-sans);
     --app-font-brand: "Architects Daughter", var(--app-font-sans);
 
-    /* 글자 크기 · 12px 기본과 역할별 제목 크기 */
+    /* 글자 크기 · 11px 비상호작용 묶음 · 12px 기본과 역할별 제목 크기 */
+    --app-font-size-group: 11px;
     --app-font-size-label: 12px;
     --app-font-size-detail: 12px;
     --app-font-size-dense: 12px;
@@ -65,9 +66,9 @@
     --app-font-size-section: 14px;
     --app-font-size-title: 16px;
 
-    /* 굵기 · 기본 400 · 현재 위치 500 · 제목·강조 600 */
+    /* 굵기 · 기본 400 · 현재 위치·제목·강조 600 */
     --app-font-weight-mark: 400;
-    --app-font-weight-active: 500;
+    --app-font-weight-active: 600;
     --app-font-weight-strong: 600;
     --app-font-weight-title: 600;
 

package/src/type/doc-branch.ts

@@ -0,0 +1,11 @@
+import type {Doc} from "@/type/doc";
+
+/**
+ * 문서 탐색의 클릭 가능한 가지 · 원래 URL과 본문을 유지
+ */
+export interface DocBranch extends Doc {
+    /**
+     * 같은 부모 아래의 문서 · order·제목·id 순, 말단 문서는 생략
+     */
+    children?: DocBranch[];
+}

package/src/type/doc-data.ts

@@ -22,6 +22,10 @@ export const docDataSchema = z.object({
      * 사이드바의 문서 묶음 경로 · 문자열도 배열로 정규화
      */
     group: groupPathSchema,
+    /**
+     * 같은 묶음 안의 부모 문서 id · 확장자 제외, ./·../ 상대 경로도 허용
+     */
+    parent: z.string().trim().min(1).optional(),
     /**
      * 묶음 안의 읽는 순서 · 미지정 문서는 뒤에서 이름순
      */

package/src/type/doc-group.ts

@@ -1,4 +1,5 @@
 import type {Doc} from "@/type/doc";
+import type {DocBranch} from "@/type/doc-branch";
 
 /**
  * 사이드바의 문서 묶음 · 같은 이름도 전체 경로로 구분
@@ -13,9 +14,9 @@ export interface DocGroup {
      */
     path: Doc["data"]["group"];
     /**
-     * 현재 묶음에 직접 속한 문서 · order·제목·id 순
+     * 현재 묶음의 부모 없는 문서 · 하위 문서는 각 문서 가지에 포함
      */
-    docs: Doc[];
+    docs: DocBranch[];
     /**
      * 현재 묶음의 하위 묶음 · navigation·이름 순
      */

package/src/type/doc.ts

@@ -13,4 +13,8 @@ export interface Doc extends DocContent {
      * 검증된 머리말
      */
     data: DocData;
+    /**
+     * 검증된 부모 문서 경로 · 최상위부터 직접 부모까지, 자신은 제외
+     */
+    ancestors: string[];
 }