for-humanity 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.2.0 — 2026-10-04
+
+- Support nested navigation with `group` name arrays while keeping single-name groups compatible.
+- Order nested sibling groups with paths in `navigation`, independently of document folders.
+- Extend active, hover and keyboard focus tree paths through ancestor groups.
+
 ## 0.1.2 — 2026-10-03
 
 Documentation and release automation update. The CLI commands and Node.js requirement are unchanged.

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.1.2
+pnpm add -D --save-exact for-humanity@0.2.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.1.2` 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.2.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.1.2` 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.2.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
@@ -94,6 +94,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.
 
 ## Write with context
 

package/dist/cli.css

@@ -295,22 +295,32 @@
   }
 }
 
-/* src/component/widget/shell/_wg-shell-nav.css */
-.wg_shellNav__root {
-  font-size: var(--app-font-size-dense);
-  line-height: var(--app-line-height-tight);
-}
-.wg_shellNav__docs {
-  display: flex;
-  flex-direction: column;
-  gap: var(--app-space-stack);
-}
-.wg_shellNav__list {
+/* src/component/widget/shell/_wg-shell-nav-list.css */
+.wg_shellNavList__root {
   margin: 0 0 0 var(--app-space-tree-inset);
   padding: 0;
   list-style: none;
 }
-.wg_shellNav__item {
+.wg_shellNavList__branch {
+  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);
+  font-size: var(--app-font-size-label);
+  line-height: 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__item {
+  display: flow-root;
   position: relative;
   &::before {
     position: absolute;
@@ -340,24 +350,36 @@
   &:where(:has(:focus-visible))::after {
     border-left-color: var(--app-color-text-strong);
   }
-  &:where(:has(~ .wg_shellNav__item:hover))::before {
+  &:where(:has(~ .wg_shellNavList__item:hover))::before {
     border-left-color: var(--app-color-text-strong);
   }
-  &:where(:has(~ .wg_shellNav__item :focus-visible))::before {
+  &:where(:has(~ .wg_shellNavList__item :focus-visible))::before {
     border-left-color: var(--app-color-text-strong);
   }
+  & > .wg_shellNavList__root {
+    margin-left: var(--app-space-tree-indent);
+  }
+  &:where(:hover) > .wg_shellNavList__branch::before {
+    border-top-color: var(--app-color-text-strong);
+  }
+  &:where(:has(:focus-visible)) > .wg_shellNavList__branch::before {
+    border-top-color: var(--app-color-text-strong);
+  }
 }
-.wg_shellNav__item--trail {
+.wg_shellNavList__item--trail {
   &::before {
     border-left-color: var(--app-color-text-strong);
   }
 }
-.wg_shellNav__item--current {
+.wg_shellNavList__item--current {
   &::after {
     border-left-color: var(--app-color-text-strong);
   }
+  & > .wg_shellNavList__branch::before {
+    border-top-color: var(--app-color-text-strong);
+  }
 }
-.wg_shellNav__link {
+.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));
@@ -365,6 +387,7 @@
   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));
@@ -388,13 +411,24 @@
     border-top-color: currentcolor;
   }
 }
-.wg_shellNav__link--active {
+.wg_shellNavList__link--active {
   color: var(--app-color-text-strong);
   font-weight: var(--app-font-weight-active);
   &::before {
     border-top-color: currentcolor;
   }
 }
+
+/* src/component/widget/shell/_wg-shell-nav.css */
+.wg_shellNav__root {
+  font-size: var(--app-font-size-dense);
+  line-height: var(--app-line-height-tight);
+}
+.wg_shellNav__docs {
+  display: flex;
+  flex-direction: column;
+  gap: var(--app-space-stack);
+}
 .wg_shellNav__group {
   margin: 0 0 4px;
   color: var(--app-color-text-muted);

package/dist/cli.js

@@ -30,7 +30,7 @@ var WgProse = (props) => {
 };
 
 // src/component/widget/shell/wg-shell.tsx
-import clsx4 from "clsx";
+import clsx5 from "clsx";
 
 // src/component/widget/shell/_function/to-toc-groups.ts
 import { takeWhile } from "es-toolkit/array";
@@ -66,7 +66,50 @@ var toTocGroups = (outline) => {
 };
 
 // src/component/widget/shell/_wg-shell-nav.tsx
+import clsx3 from "clsx";
+
+// src/component/widget/shell/_wg-shell-nav-list.tsx
 import clsx2 from "clsx";
+import { Fragment } from "react";
+import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
+var WgShellNavList = (props) => {
+  const entries = [
+    ...props.group.docs.map((doc) => ({ kind: "document", key: `doc:${doc.id}`, doc, current: doc.id === props.currentDoc?.id })),
+    ...props.group.groups.map((group) => ({
+      kind: "group",
+      key: `group:${JSON.stringify(group.path)}`,
+      group,
+      current: group.path.every((name, index) => name === props.currentDoc?.data.group[index])
+    }))
+  ];
+  const currentIndex = entries.findIndex((entry) => entry.current);
+  return /* @__PURE__ */ jsx2("ul", { className: clsx2("wg_shellNavList__root"), "aria-label": props.group.name, children: entries.map((entry, index) => /* @__PURE__ */ jsxs2(
+    "li",
+    {
+      className: clsx2("wg_shellNavList__item", {
+        "wg_shellNavList__item--trail": index < currentIndex,
+        "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 === "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 })
+        ] })
+      ]
+    },
+    entry.key
+  )) });
+};
 
 // src/constant/copy.ts
 var copy_site_title_default = "for humanity";
@@ -95,61 +138,60 @@ 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.ts
+// src/content/to-doc-groups/_to-doc-group-branches.ts
+var toDocGroupBranches = (options) => {
+  return [
+    ...Map.groupBy(
+      options.docs.filter((doc) => doc.data.group.length > options.path.length),
+      (doc) => doc.data.group[options.path.length]
+    )
+  ].map(([name, docs]) => {
+    const path = [...options.path, name];
+    return {
+      name,
+      path,
+      docs,
+      position: options.positions.get(JSON.stringify(path)) ?? options.unlistedPosition
+    };
+  }).toSorted((a, b) => a.position - b.position || a.name.localeCompare(b.name, locale_doc_group)).map((group) => {
+    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 })
+    };
+  });
+};
+
+// src/content/to-doc-groups/to-doc-groups.ts
 var toDocGroups = (options) => {
-  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))
-  }));
+  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 });
 };
 
 // src/component/widget/shell/_wg-shell-nav.tsx
-import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
+import { jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
 var WgShellNav = (props) => {
   const docGroups = toDocGroups({ docs: props.docs, navigation: props.site.navigation });
-  return /* @__PURE__ */ jsx2("nav", { className: clsx2("wg_shellNav__root"), "aria-label": copy_nav_aria_label, children: /* @__PURE__ */ jsx2("div", { className: clsx2("wg_shellNav__docs"), children: docGroups.map((group) => {
-    const currentIndex = group.docs.findIndex((doc) => doc.id === props.current);
-    return /* @__PURE__ */ jsxs2("section", { className: clsx2("wg_shellNav__docGroup"), "aria-label": group.name, children: [
-      /* @__PURE__ */ jsx2("div", { className: clsx2("wg_shellNav__group"), children: group.name }),
-      /* @__PURE__ */ jsx2("ul", { className: clsx2("wg_shellNav__list"), children: group.docs.map((doc, index) => /* @__PURE__ */ jsx2(
-        "li",
-        {
-          className: clsx2("wg_shellNav__item", {
-            "wg_shellNav__item--trail": index < currentIndex,
-            "wg_shellNav__item--current": index === currentIndex
-          }),
-          children: /* @__PURE__ */ jsx2(
-            "a",
-            {
-              className: clsx2("wg_shellNav__link", {
-                "wg_shellNav__link--active": index === currentIndex
-              }),
-              href: `/${doc.id}/`,
-              title: doc.data.label,
-              "aria-current": index === currentIndex ? "page" : void 0,
-              children: doc.data.name
-            }
-          )
-        },
-        doc.id
-      )) })
-    ] }, group.name);
-  }) }) });
+  const currentDoc = props.docs.find((doc) => doc.id === props.current);
+  return /* @__PURE__ */ jsx3("nav", { className: clsx3("wg_shellNav__root"), "aria-label": copy_nav_aria_label, children: /* @__PURE__ */ jsx3("div", { className: clsx3("wg_shellNav__docs"), children: docGroups.map((group) => /* @__PURE__ */ jsxs3("section", { className: clsx3("wg_shellNav__docGroup"), "aria-label": group.name, children: [
+    /* @__PURE__ */ jsx3("div", { className: clsx3("wg_shellNav__group"), children: group.name }),
+    /* @__PURE__ */ jsx3(WgShellNavList, { group, currentDoc })
+  ] }, group.name)) }) });
 };
 
 // src/component/widget/shell/_wg-shell-toc.tsx
-import clsx3 from "clsx";
-import { Fragment } from "react";
-import { jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
+import clsx4 from "clsx";
+import { Fragment as Fragment2 } from "react";
+import { jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
 var WgShellToc = (props) => {
-  return /* @__PURE__ */ jsxs3("nav", { className: clsx3("wg_shellToc__root"), "aria-label": copy_nav_toc_label, children: [
-    /* @__PURE__ */ jsx3("div", { className: clsx3("wg_shellToc__label"), children: copy_nav_toc_label }),
-    props.groups.map((group) => /* @__PURE__ */ jsxs3(Fragment, { children: [
-      group.part !== void 0 && /* @__PURE__ */ jsx3("div", { className: clsx3("wg_shellToc__group"), children: group.part }),
-      /* @__PURE__ */ jsx3("ul", { className: clsx3("wg_shellToc__list"), children: group.sections.map((section) => /* @__PURE__ */ jsxs3("li", { className: clsx3("wg_shellToc__item"), children: [
-        /* @__PURE__ */ jsx3("a", { className: clsx3("wg_shellToc__link"), href: `#${section.heading.slug}`, "data-toc-link": "", children: section.heading.text }),
-        section.subs.length > 0 && /* @__PURE__ */ jsx3("ul", { className: clsx3("wg_shellToc__sub"), children: section.subs.map((sub) => /* @__PURE__ */ jsx3("li", { className: clsx3("wg_shellToc__subItem"), children: /* @__PURE__ */ jsx3("a", { className: clsx3("wg_shellToc__subLink"), href: `#${sub.heading.slug}`, "data-toc-sub-link": "", children: sub.heading.text }) }, sub.heading.slug)) })
+  return /* @__PURE__ */ jsxs4("nav", { className: clsx4("wg_shellToc__root"), "aria-label": copy_nav_toc_label, children: [
+    /* @__PURE__ */ jsx4("div", { className: clsx4("wg_shellToc__label"), children: copy_nav_toc_label }),
+    props.groups.map((group) => /* @__PURE__ */ jsxs4(Fragment2, { children: [
+      group.part !== void 0 && /* @__PURE__ */ jsx4("div", { className: clsx4("wg_shellToc__group"), children: group.part }),
+      /* @__PURE__ */ jsx4("ul", { className: clsx4("wg_shellToc__list"), children: group.sections.map((section) => /* @__PURE__ */ jsxs4("li", { className: clsx4("wg_shellToc__item"), children: [
+        /* @__PURE__ */ jsx4("a", { className: clsx4("wg_shellToc__link"), href: `#${section.heading.slug}`, "data-toc-link": "", children: section.heading.text }),
+        section.subs.length > 0 && /* @__PURE__ */ jsx4("ul", { className: clsx4("wg_shellToc__sub"), children: section.subs.map((sub) => /* @__PURE__ */ jsx4("li", { className: clsx4("wg_shellToc__subItem"), children: /* @__PURE__ */ jsx4("a", { className: clsx4("wg_shellToc__subLink"), href: `#${sub.heading.slug}`, "data-toc-sub-link": "", children: sub.heading.text }) }, sub.heading.slug)) })
       ] }, section.heading.slug)) })
     ] }, group.sections[0].heading.slug))
   ] });
@@ -171,85 +213,85 @@ var asset_content_types = {
 var asset_content_type_default = "application/octet-stream";
 
 // src/component/widget/shell/wg-shell.tsx
-import { jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
+import { jsx as jsx5, jsxs as jsxs5 } from "react/jsx-runtime";
 var reloadScript = `new EventSource(${JSON.stringify(asset_reload_path)}).onmessage=function(){location.reload()}`;
 var WgShell = (props) => {
   const tocGroups = props.outline === void 0 ? [] : toTocGroups(props.outline);
-  return /* @__PURE__ */ jsxs4("html", { lang: "ko", children: [
-    /* @__PURE__ */ jsxs4("head", { children: [
-      /* @__PURE__ */ jsx4("meta", { charSet: "utf-8" }),
-      /* @__PURE__ */ jsx4("meta", { name: "viewport", content: "width=device-width, initial-scale=1" }),
-      props.site.description !== void 0 && /* @__PURE__ */ jsx4("meta", { name: "description", content: props.site.description }),
-      /* @__PURE__ */ jsx4("title", { children: props.title === void 0 ? props.site.title : `${props.title} \xB7 ${props.site.title}` }),
-      /* @__PURE__ */ jsx4("link", { rel: "icon", href: asset_favicon_path, type: "image/svg+xml" }),
-      /* @__PURE__ */ jsx4("style", { dangerouslySetInnerHTML: { __html: props.assets.fontCss } }),
-      props.assets.preload.map((href) => /* @__PURE__ */ jsx4("link", { rel: "preload", href, as: "font", type: "font/woff2", crossOrigin: "" }, href)),
-      /* @__PURE__ */ jsx4("script", { dangerouslySetInnerHTML: { __html: 'document.documentElement.style.scrollBehavior="auto"' } }),
-      /* @__PURE__ */ jsx4("link", { rel: "stylesheet", href: asset_style_path }),
-      props.assets.reload && /* @__PURE__ */ jsx4("script", { dangerouslySetInnerHTML: { __html: reloadScript } })
+  return /* @__PURE__ */ jsxs5("html", { lang: "ko", children: [
+    /* @__PURE__ */ jsxs5("head", { children: [
+      /* @__PURE__ */ jsx5("meta", { charSet: "utf-8" }),
+      /* @__PURE__ */ jsx5("meta", { name: "viewport", content: "width=device-width, initial-scale=1" }),
+      props.site.description !== void 0 && /* @__PURE__ */ jsx5("meta", { name: "description", content: props.site.description }),
+      /* @__PURE__ */ jsx5("title", { children: props.title === void 0 ? props.site.title : `${props.title} \xB7 ${props.site.title}` }),
+      /* @__PURE__ */ jsx5("link", { rel: "icon", href: asset_favicon_path, type: "image/svg+xml" }),
+      /* @__PURE__ */ jsx5("style", { dangerouslySetInnerHTML: { __html: props.assets.fontCss } }),
+      props.assets.preload.map((href) => /* @__PURE__ */ jsx5("link", { rel: "preload", href, as: "font", type: "font/woff2", crossOrigin: "" }, href)),
+      /* @__PURE__ */ jsx5("script", { dangerouslySetInnerHTML: { __html: 'document.documentElement.style.scrollBehavior="auto"' } }),
+      /* @__PURE__ */ jsx5("link", { rel: "stylesheet", href: asset_style_path }),
+      props.assets.reload && /* @__PURE__ */ jsx5("script", { dangerouslySetInnerHTML: { __html: reloadScript } })
     ] }),
-    /* @__PURE__ */ jsxs4("body", { className: clsx4("wg_shell__root"), children: [
-      /* @__PURE__ */ jsxs4("div", { className: clsx4("wg_shell__sidebar"), children: [
-        /* @__PURE__ */ jsxs4("div", { className: clsx4("wg_shell__brandRow"), children: [
-          /* @__PURE__ */ jsx4("a", { className: clsx4("wg_shell__brand"), href: "/", "aria-current": props.current === void 0 ? "page" : void 0, children: props.site.title }),
-          /* @__PURE__ */ jsx4(
+    /* @__PURE__ */ jsxs5("body", { className: clsx5("wg_shell__root"), children: [
+      /* @__PURE__ */ jsxs5("div", { className: clsx5("wg_shell__sidebar"), children: [
+        /* @__PURE__ */ jsxs5("div", { className: clsx5("wg_shell__brandRow"), children: [
+          /* @__PURE__ */ jsx5("a", { className: clsx5("wg_shell__brand"), href: "/", "aria-current": props.current === void 0 ? "page" : void 0, children: props.site.title }),
+          /* @__PURE__ */ jsx5(
             "button",
             {
-              className: clsx4("wg_shell__menuToggle"),
+              className: clsx5("wg_shell__menuToggle"),
               type: "button",
               "aria-label": copy_nav_open,
               "aria-controls": "fh-navigation-drawer",
               "aria-expanded": "false",
               "data-navigation-open": "",
-              children: /* @__PURE__ */ jsx4("svg", { className: clsx4("wg_shell__menuIcon"), viewBox: "0 0 24 24", "aria-hidden": "true", focusable: "false", children: /* @__PURE__ */ jsx4("path", { d: "M4 6h16M4 12h16M4 18h16" }) })
+              children: /* @__PURE__ */ jsx5("svg", { className: clsx5("wg_shell__menuIcon"), viewBox: "0 0 24 24", "aria-hidden": "true", focusable: "false", children: /* @__PURE__ */ jsx5("path", { d: "M4 6h16M4 12h16M4 18h16" }) })
             }
           )
         ] }),
-        /* @__PURE__ */ jsxs4("div", { className: clsx4("wg_shell__navigation"), "data-navigation": "", children: [
-          /* @__PURE__ */ jsx4(WgShellNav, { site: props.site, docs: props.docs, current: props.current }),
-          tocGroups.length > 0 && /* @__PURE__ */ jsx4(WgShellToc, { groups: tocGroups })
+        /* @__PURE__ */ jsxs5("div", { className: clsx5("wg_shell__navigation"), "data-navigation": "", children: [
+          /* @__PURE__ */ jsx5(WgShellNav, { site: props.site, docs: props.docs, current: props.current }),
+          tocGroups.length > 0 && /* @__PURE__ */ jsx5(WgShellToc, { groups: tocGroups })
         ] })
       ] }),
-      /* @__PURE__ */ jsx4("main", { className: clsx4("wg_shell__main"), children: props.children }),
-      /* @__PURE__ */ jsxs4("dialog", { className: clsx4("wg_shell__drawer"), id: "fh-navigation-drawer", "aria-labelledby": "fh-navigation-title", "data-navigation-drawer": "", children: [
-        /* @__PURE__ */ jsxs4("div", { className: clsx4("wg_shell__drawerHeader"), children: [
-          /* @__PURE__ */ jsx4("h2", { className: clsx4("wg_shell__drawerTitle"), id: "fh-navigation-title", children: copy_nav_title }),
-          /* @__PURE__ */ jsx4("button", { className: clsx4("wg_shell__drawerClose"), type: "button", "aria-label": copy_nav_close, "data-navigation-close": "", children: /* @__PURE__ */ jsx4("svg", { className: clsx4("wg_shell__menuIcon"), viewBox: "0 0 24 24", "aria-hidden": "true", focusable: "false", children: /* @__PURE__ */ jsx4("path", { d: "m6 6 12 12M18 6 6 18" }) }) })
+      /* @__PURE__ */ jsx5("main", { className: clsx5("wg_shell__main"), children: props.children }),
+      /* @__PURE__ */ jsxs5("dialog", { className: clsx5("wg_shell__drawer"), id: "fh-navigation-drawer", "aria-labelledby": "fh-navigation-title", "data-navigation-drawer": "", children: [
+        /* @__PURE__ */ jsxs5("div", { className: clsx5("wg_shell__drawerHeader"), children: [
+          /* @__PURE__ */ jsx5("h2", { className: clsx5("wg_shell__drawerTitle"), id: "fh-navigation-title", children: copy_nav_title }),
+          /* @__PURE__ */ jsx5("button", { className: clsx5("wg_shell__drawerClose"), type: "button", "aria-label": copy_nav_close, "data-navigation-close": "", children: /* @__PURE__ */ jsx5("svg", { className: clsx5("wg_shell__menuIcon"), viewBox: "0 0 24 24", "aria-hidden": "true", focusable: "false", children: /* @__PURE__ */ jsx5("path", { d: "m6 6 12 12M18 6 6 18" }) }) })
         ] }),
-        /* @__PURE__ */ jsx4("div", { className: clsx4("wg_shell__drawerContent"), "data-navigation-content": "" })
+        /* @__PURE__ */ jsx5("div", { className: clsx5("wg_shell__drawerContent"), "data-navigation-content": "" })
       ] }),
-      /* @__PURE__ */ jsx4("img", { className: clsx4("wg_shell__cursorFace"), src: asset_favicon_path, width: "24", height: "24", alt: "", "aria-hidden": "true", draggable: false, "data-cursor-face": "" }),
-      /* @__PURE__ */ jsx4("script", { type: "module", src: asset_client_path })
+      /* @__PURE__ */ jsx5("img", { className: clsx5("wg_shell__cursorFace"), src: asset_favicon_path, width: "24", height: "24", alt: "", "aria-hidden": "true", draggable: false, "data-cursor-face": "" }),
+      /* @__PURE__ */ jsx5("script", { type: "module", src: asset_client_path })
     ] })
   ] });
 };
 
 // src/page/doc/pg-doc.tsx
-import { jsx as jsx5 } from "react/jsx-runtime";
+import { jsx as jsx6 } from "react/jsx-runtime";
 var PgDoc = (props) => {
-  return /* @__PURE__ */ jsx5(WgShell, { site: props.site, docs: props.docs, assets: props.assets, title: props.doc.data.name, current: props.doc.id, outline: props.doc.outline, children: /* @__PURE__ */ jsx5(WgProse, { html: props.doc.html }) });
+  return /* @__PURE__ */ jsx6(WgShell, { site: props.site, docs: props.docs, assets: props.assets, title: props.doc.data.name, current: props.doc.id, outline: props.doc.outline, children: /* @__PURE__ */ jsx6(WgProse, { html: props.doc.html }) });
 };
 
 // src/page/home/pg-home.tsx
-import { jsx as jsx6 } from "react/jsx-runtime";
+import { jsx as jsx7 } from "react/jsx-runtime";
 var PgHome = (props) => {
-  return /* @__PURE__ */ jsx6(WgShell, { site: props.site, docs: props.docs, assets: props.assets, outline: props.home?.outline, children: props.home === void 0 ? /* @__PURE__ */ jsx6(WgProse, { head: { title: props.site.title, lead: copy_home_missing } }) : /* @__PURE__ */ jsx6(WgProse, { html: props.home.html }) });
+  return /* @__PURE__ */ jsx7(WgShell, { site: props.site, docs: props.docs, assets: props.assets, outline: props.home?.outline, children: props.home === void 0 ? /* @__PURE__ */ jsx7(WgProse, { head: { title: props.site.title, lead: copy_home_missing } }) : /* @__PURE__ */ jsx7(WgProse, { html: props.home.html }) });
 };
 
 // src/app.tsx
-import { jsx as jsx7 } from "react/jsx-runtime";
+import { jsx as jsx8 } from "react/jsx-runtime";
 var toHtml = (page) => {
   return `<!DOCTYPE html>${renderToStaticMarkup(page)}`;
 };
 var createApp = (options) => {
   const app = new Hono();
-  app.get("/", (c) => c.html(toHtml(/* @__PURE__ */ jsx7(PgHome, { site: options.site, docs: options.store.docs, assets: options.assets, home: options.store.home }))));
+  app.get("/", (c) => c.html(toHtml(/* @__PURE__ */ jsx8(PgHome, { site: options.site, docs: options.store.docs, assets: options.assets, home: options.store.home }))));
   app.get(
     "/:slug{.+}/",
     ssgParams(() => options.store.docs.map((doc) => ({ slug: doc.id }))),
     (c) => {
       const doc = options.store.docs.find((entry) => entry.id === c.req.param("slug"));
-      return doc === void 0 ? c.notFound() : c.html(toHtml(/* @__PURE__ */ jsx7(PgDoc, { site: options.site, docs: options.store.docs, assets: options.assets, doc })));
+      return doc === void 0 ? c.notFound() : c.html(toHtml(/* @__PURE__ */ jsx8(PgDoc, { site: options.site, docs: options.store.docs, assets: options.assets, doc })));
     }
   );
   return app;
@@ -935,7 +977,7 @@ import { VFile } from "vfile";
 import { parse as parseYaml } from "yaml";
 
 // src/type/doc-data.ts
-import { z } from "zod";
+import { z as z2 } from "zod";
 
 // src/constant/doc.ts
 var doc_type = {
@@ -944,28 +986,32 @@ var doc_type = {
 };
 var doc_order_default = Number.MAX_SAFE_INTEGER;
 
+// src/type/group-path.ts
+import { z } from "zod";
+var groupPathSchema = z.union([z.string().trim().min(1), z.array(z.string().trim().min(1)).min(1)]).transform((path) => typeof path === "string" ? [path] : path);
+
 // src/type/doc-data.ts
-var docDataSchema = z.object({
+var docDataSchema = z2.object({
   /**
    * 문서 이름 · 제목·목록 · 같은 첫 글자 허용
    */
-  name: z.string().trim().min(1),
+  name: z2.string().trim().min(1),
   /**
    * 짧은 문서 설명 · 사이드바 툴팁
    */
-  label: z.string(),
+  label: z2.string(),
   /**
    * 문서 종류 · blueprint 전용 표현 미구현
    */
-  type: z.enum(doc_type).default(doc_type.document),
+  type: z2.enum(doc_type).default(doc_type.document),
   /**
-   * 사이드바의 문서 묶음
+   * 사이드바의 문서 묶음 경로 · 문자열도 배열로 정규화
    */
-  group: z.string().trim().min(1),
+  group: groupPathSchema,
   /**
    * 묶음 안의 읽는 순서 · 미지정 문서는 뒤에서 이름순
    */
-  order: z.number().int().nonnegative().default(doc_order_default)
+  order: z2.number().int().nonnegative().default(doc_order_default)
 });
 
 // src/content/read-docs.ts
@@ -1068,7 +1114,7 @@ var createDevApp = (options) => {
 };
 
 // src/type/site-config.ts
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 
 // src/constant/status.ts
 var status_kind = {
@@ -1081,36 +1127,36 @@ var status_default_phrases = [
 ];
 
 // src/type/site-config.ts
-var siteConfigSchema = z2.object({
+var siteConfigSchema = z3.object({
   /**
    * 사이드바 이름과 탭 제목
    */
-  title: z2.string().default(copy_site_title_default),
+  title: z3.string().default(copy_site_title_default),
   /**
    * HTML 설명 메타데이터 · 선택
    */
-  description: z2.string().optional(),
+  description: z3.string().optional(),
   /**
-   * 탐색 묶음의 읽는 순서 · 미지정 묶음은 뒤에서 이름순
+   * 탐색 묶음 경로의 읽는 순서 · 미지정 형제 묶음은 뒤에서 이름순
    */
-  navigation: z2.array(z2.string().trim().min(1)).refine((groups) => new Set(groups).size === groups.length, copy_error_navigation_clash).default([...site_navigation_default]),
+  navigation: z3.array(groupPathSchema).refine((groups) => new Set(groups.map((path) => JSON.stringify(path))).size === groups.length, copy_error_navigation_clash).default(site_navigation_default.map((name) => [name])),
   /**
    * 본문에서 상태 표지로 표시할 문구
    */
-  status: z2.array(
-    z2.object({
+  status: z3.array(
+    z3.object({
       /**
        * 찾을 문구 원문
        */
-      phrase: z2.string().min(1).refine((phrase) => phrase.trim().length > 0),
+      phrase: z3.string().min(1).refine((phrase) => phrase.trim().length > 0),
       /**
        * 상태 표지의 색 종류
        */
-      kind: z2.enum(status_kind),
+      kind: z3.enum(status_kind),
       /**
        * 문구 뒤의 YYYY-MM-DD 날짜 포함 여부
        */
-      date: z2.boolean().optional()
+      date: z3.boolean().optional()
     })
   ).default(status_default_phrases)
 });

package/package.json

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

@@ -0,0 +1,158 @@
+/*
+ * 재귀 문서 목록 · 단계별 가지와 조상 경로의 1px 트리
+ */
+.wg_shellNavList__root {
+    margin: 0 0 0 var(--app-space-tree-inset);
+    padding: 0;
+    list-style: none;
+}
+
+.wg_shellNavList__branch {
+    /* 하위 묶음도 문서와 같은 첫 줄 기준으로 가지 연결 */
+    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);
+    font-size: var(--app-font-size-label);
+    line-height: 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__item {
+    /* 하위 목록을 포함해 다음 형제까지 줄기 연결 */
+    display: flow-root;
+
+    /* 세로 줄기는 각 항목 기준 · 마지막 항목의 첫 줄 가운데에서 종료 */
+    position: relative;
+
+    &::before {
+        position: absolute;
+        top: 0;
+        bottom: 0;
+        left: 0;
+        border-left: 1px solid var(--app-color-border-soft);
+        content: "";
+        pointer-events: none;
+    }
+
+    &:where(:last-child)::before {
+        bottom: auto;
+        height: calc(0.5lh + var(--app-space-tree-row));
+    }
+
+    /* hover·키보드 포커스의 도착점 · 첫 줄 아래는 기본 줄기 유지 */
+    &::after {
+        position: absolute;
+        top: 0;
+        left: 0;
+        height: calc(0.5lh + var(--app-space-tree-row));
+        border-left: 1px solid transparent;
+        content: "";
+        pointer-events: none;
+    }
+
+    &:where(:hover)::after {
+        border-left-color: var(--app-color-text-strong);
+    }
+
+    &:where(:has(:focus-visible))::after {
+        border-left-color: var(--app-color-text-strong);
+    }
+
+    /* 뒤 항목까지의 세로 경로 · 같은 목록의 형제 안에서만 연결 */
+    &:where(:has(~ .wg_shellNavList__item:hover))::before {
+        border-left-color: var(--app-color-text-strong);
+    }
+
+    &:where(:has(~ .wg_shellNavList__item :focus-visible))::before {
+        border-left-color: var(--app-color-text-strong);
+    }
+
+    & > .wg_shellNavList__root {
+        margin-left: var(--app-space-tree-indent);
+    }
+
+    /* 하위 문서를 탐색할 때 조상 묶음의 가지도 함께 연결 */
+    &:where(:hover) > .wg_shellNavList__branch::before {
+        border-top-color: var(--app-color-text-strong);
+    }
+
+    &:where(:has(:focus-visible)) > .wg_shellNavList__branch::before {
+        border-top-color: var(--app-color-text-strong);
+    }
+}
+
+.wg_shellNavList__item--trail {
+    &::before {
+        border-left-color: var(--app-color-text-strong);
+    }
+}
+
+.wg_shellNavList__item--current {
+    &::after {
+        border-left-color: var(--app-color-text-strong);
+    }
+
+    & > .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;
+    }
+
+    &: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;
+    }
+}

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

@@ -0,0 +1,72 @@
+import clsx from "clsx";
+import {Fragment} from "react";
+import type {Doc} from "@/type/doc";
+import type {DocGroup} from "@/type/doc-group";
+import "./_wg-shell-nav-list.css";
+
+/**
+ * 한 단계의 문서 목록과 하위 묶음 · 재귀에서도 같은 탐색 표현 유지
+ */
+export interface WgShellNavListProps {
+    /**
+     * 현재 단계의 문서와 하위 묶음
+     */
+    group: DocGroup;
+    /**
+     * 현재 문서 · 조상 묶음의 경로까지 표시
+     */
+    currentDoc?: Doc;
+}
+
+export const WgShellNavList = (props: WgShellNavListProps) => {
+    const entries = [
+        ...props.group.docs.map((doc) => ({kind: "document" as const, key: `doc:${doc.id}`, doc, current: doc.id === props.currentDoc?.id})),
+        ...props.group.groups.map((group) => ({
+            kind: "group" as const,
+            key: `group:${JSON.stringify(group.path)}`,
+            group,
+            current: group.path.every((name, index) => name === props.currentDoc?.data.group[index]),
+        })),
+    ];
+    const currentIndex = entries.findIndex((entry) => entry.current);
+
+    return (
+        <ul className={clsx("wg_shellNavList__root")} aria-label={props.group.name}>
+            {/**
+             * 현재 경로 앞의 줄기와 도착 가지 · 문서 링크는 원래 파일 URL 사용
+             */}
+            {entries.map((entry, index) => (
+                <li
+                    className={clsx("wg_shellNavList__item", {
+                        "wg_shellNavList__item--trail": index < currentIndex,
+                        "wg_shellNavList__item--current": entry.current,
+                    })}
+                    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>
+                    )}
+                    {/**
+                     * 하위 묶음 · 같은 목록을 재귀로 이어 깊이에 따라 들여쓰기
+                     */}
+                    {entry.kind === "group" && (
+                        <Fragment>
+                            <span className={clsx("wg_shellNavList__branch")}>{entry.group.name}</span>
+                            <WgShellNavList group={entry.group} currentDoc={props.currentDoc} />
+                        </Fragment>
+                    )}
+                </li>
+            ))}
+        </ul>
+    );
+};

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

@@ -12,120 +12,6 @@
     gap: var(--app-space-stack);
 }
 
-.wg_shellNav__list {
-    margin: 0 0 0 var(--app-space-tree-inset);
-    padding: 0;
-    list-style: none;
-}
-
-.wg_shellNav__item {
-    /* 세로 줄기는 각 항목 기준 · 마지막 항목의 첫 줄 가운데에서 종료 */
-    position: relative;
-
-    &::before {
-        position: absolute;
-        top: 0;
-        bottom: 0;
-        left: 0;
-        border-left: 1px solid var(--app-color-border-soft);
-        content: "";
-        pointer-events: none;
-    }
-
-    &:where(:last-child)::before {
-        bottom: auto;
-        height: calc(0.5lh + var(--app-space-tree-row));
-    }
-
-    /* hover·키보드 포커스의 도착점 · 첫 줄 아래는 기본 줄기 유지 */
-    &::after {
-        position: absolute;
-        top: 0;
-        left: 0;
-        height: calc(0.5lh + var(--app-space-tree-row));
-        border-left: 1px solid transparent;
-        content: "";
-        pointer-events: none;
-    }
-
-    &:where(:hover)::after {
-        border-left-color: var(--app-color-text-strong);
-    }
-
-    &:where(:has(:focus-visible))::after {
-        border-left-color: var(--app-color-text-strong);
-    }
-
-    /* 뒤 항목까지의 세로 경로 · 같은 목록의 형제 안에서만 연결 */
-    &:where(:has(~ .wg_shellNav__item:hover))::before {
-        border-left-color: var(--app-color-text-strong);
-    }
-
-    &:where(:has(~ .wg_shellNav__item :focus-visible))::before {
-        border-left-color: var(--app-color-text-strong);
-    }
-}
-
-.wg_shellNav__item--trail {
-    &::before {
-        border-left-color: var(--app-color-text-strong);
-    }
-}
-
-.wg_shellNav__item--current {
-    &::after {
-        border-left-color: var(--app-color-text-strong);
-    }
-}
-
-.wg_shellNav__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;
-
-    &::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;
-    }
-
-    &: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_shellNav__link--active {
-    color: var(--app-color-text-strong);
-    font-weight: var(--app-font-weight-active);
-
-    &::before {
-        border-top-color: currentcolor;
-    }
-}
-
 .wg_shellNav__group {
     margin: 0 0 4px;
     color: var(--app-color-text-muted);

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

@@ -1,6 +1,7 @@
 import clsx from "clsx";
+import {WgShellNavList} from "@/component/widget/shell/_wg-shell-nav-list";
 import {copy_nav_aria_label} from "@/constant/copy";
-import {toDocGroups} from "@/content/to-doc-groups";
+import {toDocGroups} from "@/content/to-doc-groups/to-doc-groups";
 import type {Doc} from "@/type/doc";
 import type {SiteConfig} from "@/type/site-config";
 import "./_wg-shell-nav.css";
@@ -25,6 +26,7 @@ export interface WgShellNavProps {
 
 export const WgShellNav = (props: WgShellNavProps) => {
     const docGroups = toDocGroups({docs: props.docs, navigation: props.site.navigation});
+    const currentDoc = props.docs.find((doc) => doc.id === props.current);
 
     return (
         <nav className={clsx("wg_shellNav__root")} aria-label={copy_nav_aria_label}>
@@ -35,40 +37,12 @@ export const WgShellNav = (props: WgShellNavProps) => {
                 {/**
                  * 묶음 이름과 독립 문서 · 제목이 링크의 접근 가능한 이름
                  */}
-                {docGroups.map((group) => {
-                    const currentIndex = group.docs.findIndex((doc) => doc.id === props.current);
-
-                    return (
-                        <section className={clsx("wg_shellNav__docGroup")} key={group.name} aria-label={group.name}>
-                            <div className={clsx("wg_shellNav__group")}>{group.name}</div>
-                            {/**
-                             * 현재 문서와 묶음 시작부터 이어지는 세로 경로 표시
-                             */}
-                            <ul className={clsx("wg_shellNav__list")}>
-                                {group.docs.map((doc, index) => (
-                                    <li
-                                        className={clsx("wg_shellNav__item", {
-                                            "wg_shellNav__item--trail": index < currentIndex,
-                                            "wg_shellNav__item--current": index === currentIndex,
-                                        })}
-                                        key={doc.id}
-                                    >
-                                        <a
-                                            className={clsx("wg_shellNav__link", {
-                                                "wg_shellNav__link--active": index === currentIndex,
-                                            })}
-                                            href={`/${doc.id}/`}
-                                            title={doc.data.label}
-                                            aria-current={index === currentIndex ? "page" : undefined}
-                                        >
-                                            {doc.data.name}
-                                        </a>
-                                    </li>
-                                ))}
-                            </ul>
-                        </section>
-                    );
-                })}
+                {docGroups.map((group) => (
+                    <section className={clsx("wg_shellNav__docGroup")} key={group.name} aria-label={group.name}>
+                        <div className={clsx("wg_shellNav__group")}>{group.name}</div>
+                        <WgShellNavList group={group} currentDoc={currentDoc} />
+                    </section>
+                ))}
             </div>
         </nav>
     );

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

@@ -9,6 +9,8 @@ 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 {toDocGroups} from "@/content/to-doc-groups/to-doc-groups";
+import {docDataSchema} from "@/type/doc-data";
 import {siteConfigSchema} from "@/type/site-config";
 
 test("documents with the same initial retain distinct URLs", async (t) => {
@@ -67,6 +69,85 @@ test("navigation shows every document group in reading order without document ic
     assert.match(html, /href="\/writing\/"[^>]*aria-current="page"/);
 });
 
+test("group paths preserve literal names and reject empty or invalid segments", () => {
+    const data = {name: "Guide", label: "Guide"};
+
+    assert.deepEqual(docDataSchema.parse({...data, group: " Guide "}).group, ["Guide"]);
+    assert.deepEqual(docDataSchema.parse({...data, group: [" Projects ", "Example project", "Research"]}).group, ["Projects", "Example project", "Research"]);
+    assert.deepEqual(docDataSchema.parse({...data, group: "Research, decisions / notes"}).group, ["Research, decisions / notes"]);
+
+    for (const group of ["", " ", [], ["Projects", " "], ["Projects", 1], [["Projects"]], null]) {
+        assert.equal(docDataSchema.safeParse({...data, group}).success, false);
+    }
+
+    assert.equal(siteConfigSchema.safeParse({navigation: ["Guide", [" Guide "]]}).success, false);
+    assert.equal(siteConfigSchema.safeParse({navigation: [["Projects", ""]]}).success, false);
+    assert.equal(siteConfigSchema.safeParse({navigation: []}).success, true);
+});
+
+test("nested groups follow metadata paths and keep sibling branches and document URLs distinct", async (t) => {
+    const root = await mkdtemp(join(tmpdir(), "for-humanity-groups-"));
+    const site = siteConfigSchema.parse({navigation: ["Guide", ["Projects", "Atlas", "Research"], ["Projects", "Atlas", "Decisions"]]});
+
+    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-two.md"), "---\nname: More guide\nlabel: Guide\ngroup: [Guide]\n---\n\nText.\n"),
+        writeFile(join(root, "overview.md"), "---\nname: Overview\nlabel: Overview\ngroup: [Projects, Atlas]\n---\n\nText.\n"),
+        writeFile(join(root, "parts.md"), "---\nname: Parts\nlabel: Parts\ngroup: [Projects, Atlas, Research]\norder: 1\n---\n\nText.\n"),
+        writeFile(join(root, "authoring.md"), "---\nname: Authoring\nlabel: Authoring\ngroup: [Projects, Atlas, Research]\norder: 2\n---\n\nText.\n"),
+        writeFile(join(root, "decision.md"), "---\nname: Decision\nlabel: Decision\ngroup: [Projects, Atlas, Decisions]\n---\n\nText.\n"),
+        writeFile(join(root, "other.md"), "---\nname: Other research\nlabel: Other research\ngroup: [Projects, Beacon, Research]\n---\n\nText.\n"),
+        writeFile(join(root, "deep.md"), "---\nname: Deep research\nlabel: Deep research\ngroup: [Projects, Atlas, Research, Archive, Drafts]\n---\n\nText.\n"),
+    ]);
+
+    const docs = await readDocs({root, processor: createProcessor({site, root})});
+    const groups = toDocGroups({docs, navigation: site.navigation});
+
+    assert.deepEqual(
+        groups.map((group) => group.name),
+        ["Guide", "Projects"],
+    );
+    assert.deepEqual(
+        groups[0].docs.map((doc) => doc.id),
+        ["guide", "guide-two"],
+    );
+    assert.deepEqual(
+        groups[1].groups.map((group) => group.name),
+        ["Atlas", "Beacon"],
+    );
+    assert.deepEqual(
+        groups[1].groups[0].docs.map((doc) => doc.id),
+        ["overview"],
+    );
+    assert.deepEqual(
+        groups[1].groups[0].groups.map((group) => group.name),
+        ["Research", "Decisions"],
+    );
+    assert.deepEqual(
+        groups[1].groups[0].groups[0].docs.map((doc) => doc.id),
+        ["parts", "authoring"],
+    );
+    assert.deepEqual(
+        groups[1].groups[1].groups[0].docs.map((doc) => doc.id),
+        ["other"],
+    );
+    assert.equal(groups[1].groups[0].groups[0].groups[0].groups[0].name, "Drafts");
+    assert.deepEqual(toDocGroups({docs: docs.toReversed(), navigation: site.navigation}), groups);
+
+    const html = renderToStaticMarkup(WgShellNav({site, docs, current: "authoring"}));
+
+    assert.match(html, /href="\/authoring\/"[^>]*aria-current="page"/);
+    assert.match(html, /Atlas<\/span><ul\b/);
+    assert.match(html, /Research<\/span><ul\b/);
+    assert.equal([...html.matchAll(/href="\/authoring\/"/g)].length, 1);
+    assert.equal([...html.matchAll(/>Research<\/span>/g)].length, 2);
+    assert.equal([...html.matchAll(/wg_shellNavList__item--current/g)].length, 3);
+    assert.doesNotMatch(renderToStaticMarkup(WgShellNav({site, docs})), /aria-current="page"|wg_shellNavList__item--current/);
+    assert.ok(html.indexOf('href="/parts/"') < html.indexOf('href="/authoring/"'));
+    assert.doesNotMatch(html, /<details\b/);
+});
+
 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/to-doc-groups/_to-doc-group-branches.ts

@@ -0,0 +1,58 @@
+import {locale_doc_group, locale_doc_name} from "@/constant/locale";
+import type {Doc} from "@/type/doc";
+import type {DocGroup} from "@/type/doc-group";
+
+/**
+ * 같은 부모의 문서를 다음 경로 단계로 묶는 재귀 입력
+ */
+interface DocGroupBranchesOptions {
+    /**
+     * 부모 경로에 속한 문서
+     */
+    docs: readonly Doc[];
+    /**
+     * 부모까지의 경로 · 최상위는 빈 배열
+     */
+    path: DocGroup["path"];
+    /**
+     * 전체 경로의 JSON 키와 navigation 위치
+     */
+    positions: ReadonlyMap<string, number>;
+    /**
+     * 미지정 경로를 지정한 묶음 뒤에 놓는 위치
+     */
+    unlistedPosition: number;
+}
+
+/**
+ * 각 단계의 직접 문서와 하위 묶음을 분리 · 고정된 깊이 제한 없이 구성
+ */
+export const toDocGroupBranches = (options: DocGroupBranchesOptions): DocGroup[] => {
+    return [
+        ...Map.groupBy(
+            options.docs.filter((doc) => doc.data.group.length > options.path.length),
+            (doc) => doc.data.group[options.path.length],
+        ),
+    ]
+        .map(([name, docs]) => {
+            const path = [...options.path, name];
+
+            return {
+                name,
+                path,
+                docs,
+                position: options.positions.get(JSON.stringify(path)) ?? options.unlistedPosition,
+            };
+        })
+        .toSorted((a, b) => a.position - b.position || a.name.localeCompare(b.name, locale_doc_group))
+        .map((group) => {
+            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}),
+            };
+        });
+};

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

@@ -0,0 +1,14 @@
+import {toDocGroupBranches} from "@/content/to-doc-groups/_to-doc-group-branches";
+import type {Doc} from "@/type/doc";
+import type {SiteConfig} from "@/type/site-config";
+
+/**
+ * 메타데이터 경로로 읽는 순서를 가진 문서 계층 구성
+ * navigation의 첫 지정을 조상에도 적용 · 미지정 형제 묶음은 이름순
+ */
+export const toDocGroups = (options: {docs: readonly Doc[]; navigation: SiteConfig["navigation"]}) => {
+    // 같은 조상을 지정한 경로는 최초 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});
+};

package/src/type/doc-data.ts

@@ -1,5 +1,6 @@
 import {z} from "zod";
 import {doc_order_default, doc_type} from "@/constant/doc";
+import {groupPathSchema} from "@/type/group-path";
 
 /**
  * 문서 frontmatter 스키마 · 검증 실패 시 빌드 중단
@@ -18,9 +19,9 @@ export const docDataSchema = z.object({
      */
     type: z.enum(doc_type).default(doc_type.document),
     /**
-     * 사이드바의 문서 묶음
+     * 사이드바의 문서 묶음 경로 · 문자열도 배열로 정규화
      */
-    group: z.string().trim().min(1),
+    group: groupPathSchema,
     /**
      * 묶음 안의 읽는 순서 · 미지정 문서는 뒤에서 이름순
      */

package/src/type/doc-group.ts

@@ -0,0 +1,23 @@
+import type {Doc} from "@/type/doc";
+
+/**
+ * 사이드바의 문서 묶음 · 같은 이름도 전체 경로로 구분
+ */
+export interface DocGroup {
+    /**
+     * 현재 단계의 표시 이름
+     */
+    name: string;
+    /**
+     * 최상위부터 현재 단계까지의 경로
+     */
+    path: Doc["data"]["group"];
+    /**
+     * 현재 묶음에 직접 속한 문서 · order·제목·id 순
+     */
+    docs: Doc[];
+    /**
+     * 현재 묶음의 하위 묶음 · navigation·이름 순
+     */
+    groups: DocGroup[];
+}

package/src/type/group-path.ts

@@ -0,0 +1,7 @@
+import {z} from "zod";
+
+/**
+ * 탐색 묶음 경로 · 기존 단일 이름과 중첩 배열을 한 번만 정규화
+ * 쉼표·슬래시는 이름 그대로 유지하며 빈 경로·단계는 거부
+ */
+export const groupPathSchema = z.union([z.string().trim().min(1), z.array(z.string().trim().min(1)).min(1)]).transform((path) => (typeof path === "string" ? [path] : path));

package/src/type/site-config.ts

@@ -2,6 +2,7 @@ import {z} from "zod";
 import {copy_error_navigation_clash, copy_site_title_default} from "@/constant/copy";
 import {site_navigation_default} from "@/constant/site";
 import {status_default_phrases, status_kind} from "@/constant/status";
+import {groupPathSchema} from "@/type/group-path";
 
 /**
  * for-humanity.config.mjs 설정 스키마
@@ -17,12 +18,12 @@ export const siteConfigSchema = z.object({
      */
     description: z.string().optional(),
     /**
-     * 탐색 묶음의 읽는 순서 · 미지정 묶음은 뒤에서 이름순
+     * 탐색 묶음 경로의 읽는 순서 · 미지정 형제 묶음은 뒤에서 이름순
      */
     navigation: z
-        .array(z.string().trim().min(1))
-        .refine((groups) => new Set(groups).size === groups.length, copy_error_navigation_clash)
-        .default([...site_navigation_default]),
+        .array(groupPathSchema)
+        .refine((groups) => new Set(groups.map((path) => JSON.stringify(path))).size === groups.length, copy_error_navigation_clash)
+        .default(site_navigation_default.map((name) => [name])),
     /**
      * 본문에서 상태 표지로 표시할 문구
      */

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

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