@limcpf/everything-is-a-markdown 0.5.3 → 0.5.4

package/README.ko.md

@@ -83,6 +83,9 @@ bun run build -- --vault ./test-vault --out ./dist
 
 - `publish: true`  
   이 값이 `true`인 문서만 빌드 결과에 포함됩니다.
+- `prefix: "A-01"`  
+  문서의 공개 식별자이자 라우트(`/A-01/`) 기준입니다.  
+  `publish: true`인데 `prefix`가 없으면 빌드 경고를 출력하고 문서를 제외합니다.
 
 선택:
 
@@ -90,8 +93,6 @@ bun run build -- --vault ./test-vault --out ./dist
   `publish: true`여도 문서를 제외합니다.
 - `title: "..."`  
   문서 제목. 없으면 파일명을 사용합니다.
-- `prefix: "A-01"`  
-  탐색기 제목 앞과 본문 메타 줄에 표시할 짧은 코드.
 - `branch: dev`  
   브랜치 필터 분류값.
 - `description: "..."`  

package/README.md

@@ -83,6 +83,9 @@ Required:
 
 - `publish: true`  
   Only documents with this value are included in build output.
+- `prefix: "A-01"`  
+  Public identifier for the document route (`/A-01/`).  
+  If `publish: true` but `prefix` is missing, the document is skipped with a build warning.
 
 Optional:
 
@@ -90,8 +93,6 @@ Optional:
   Excludes the document even if `publish: true`.
 - `title: "..."`  
   Display title. If missing, file name is used.
-- `prefix: "A-01"`  
-  Short code shown before the title in the explorer and meta line.
 - `branch: dev`  
   Branch filter label.
 - `description: "..."`  

package/bun.lock

@@ -12,6 +12,7 @@
         "shiki": "^3.2.1",
       },
       "devDependencies": {
+        "@playwright/test": "^1.58.2",
         "@types/markdown-it": "^14.1.2",
         "@types/picomatch": "^4.0.2",
         "bun-types": "^1.3.8",
@@ -19,6 +20,8 @@
     },
   },
   "packages": {
+    "@playwright/test": ["@playwright/test@1.58.2", "", { "dependencies": { "playwright": "1.58.2" }, "bin": { "playwright": "cli.js" } }, "sha512-akea+6bHYBBfA9uQqSYmlJXn61cTa+jbO87xVLCWbTqbWadRVmhxlXATaOjOgcBaWU4ePo0wB41KMFv3o35IXA=="],
+
     "@shikijs/core": ["@shikijs/core@3.22.0", "", { "dependencies": { "@shikijs/types": "3.22.0", "@shikijs/vscode-textmate": "^10.0.2", "@types/hast": "^3.0.4", "hast-util-to-html": "^9.0.5" } }, "sha512-iAlTtSDDbJiRpvgL5ugKEATDtHdUVkqgHDm/gbD2ZS9c88mx7G1zSYjjOxp5Qa0eaW0MAQosFRmJSk354PRoQA=="],
 
     "@shikijs/engine-javascript": ["@shikijs/engine-javascript@3.22.0", "", { "dependencies": { "@shikijs/types": "3.22.0", "@shikijs/vscode-textmate": "^10.0.2", "oniguruma-to-es": "^4.3.4" } }, "sha512-jdKhfgW9CRtj3Tor0L7+yPwdG3CgP7W+ZEqSsojrMzCjD1e0IxIbwUMDDpYlVBlC08TACg4puwFGkZfLS+56Tw=="],
@@ -75,6 +78,8 @@
 
     "extend-shallow": ["extend-shallow@2.0.1", "", { "dependencies": { "is-extendable": "^0.1.0" } }, "sha512-zCnTtlxNoAiDc3gqY2aYAWFx7XWWiasuF2K8Me5WbN8otHKTUKBwjPtNpRs/rbUZm7KxWAaNj7P1a/p52GbVug=="],
 
+    "fsevents": ["fsevents@2.3.2", "", { "os": "darwin" }, "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA=="],
+
     "gray-matter": ["gray-matter@4.0.3", "", { "dependencies": { "js-yaml": "^3.13.1", "kind-of": "^6.0.2", "section-matter": "^1.0.0", "strip-bom-string": "^1.0.0" } }, "sha512-5v6yZd4JK3eMI3FqqCouswVqwugaA9r4dNZB1wwcmrD02QkV5H0y7XBQW8QwQqEaZY1pM9aqORSORhJRdNK44Q=="],
 
     "hast-util-to-html": ["hast-util-to-html@9.0.5", "", { "dependencies": { "@types/hast": "^3.0.0", "@types/unist": "^3.0.0", "ccount": "^2.0.0", "comma-separated-tokens": "^2.0.0", "hast-util-whitespace": "^3.0.0", "html-void-elements": "^3.0.0", "mdast-util-to-hast": "^13.0.0", "property-information": "^7.0.0", "space-separated-tokens": "^2.0.0", "stringify-entities": "^4.0.0", "zwitch": "^2.0.4" } }, "sha512-OguPdidb+fbHQSU4Q4ZiLKnzWo8Wwsf5bZfbvu7//a9oTYoqD/fWpe96NuHkoS9h0ccGOTe0C4NGXdtS0iObOw=="],
@@ -113,6 +118,10 @@
 
     "picomatch": ["picomatch@4.0.3", "", {}, "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q=="],
 
+    "playwright": ["playwright@1.58.2", "", { "dependencies": { "playwright-core": "1.58.2" }, "optionalDependencies": { "fsevents": "2.3.2" }, "bin": { "playwright": "cli.js" } }, "sha512-vA30H8Nvkq/cPBnNw4Q8TWz1EJyqgpuinBcHET0YVJVFldr8JDNiU9LaWAE1KqSkRYazuaBhTpB5ZzShOezQ6A=="],
+
+    "playwright-core": ["playwright-core@1.58.2", "", { "bin": { "playwright-core": "cli.js" } }, "sha512-yZkEtftgwS8CsfYo7nm0KE8jsvm6i/PTgVtB8DL726wNf6H2IMsDuxCpJj59KDaxCtSnrWan2AeDqM7JBaultg=="],
+
     "property-information": ["property-information@7.1.0", "", {}, "sha512-TwEZ+X+yCJmYfL7TPUOcvBZ4QfoT5YenQiJuX//0th53DE6w0xxLEtfK3iyryQFddXuvkIk51EEgrJQ0WJkOmQ=="],
 
     "punycode.js": ["punycode.js@2.3.1", "", {}, "sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA=="],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@limcpf/everything-is-a-markdown",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "license": "MIT",
   "private": false,
   "type": "module",
@@ -20,7 +20,9 @@
     "blog": "bun run src/cli.ts",
     "build": "bun run src/cli.ts build",
     "dev": "bun run src/cli.ts dev",
-    "clean": "bun run src/cli.ts clean"
+    "clean": "bun run src/cli.ts clean",
+    "test:e2e": "playwright test",
+    "test:e2e:focus-trap": "playwright test tests/e2e/mobile-sidebar-focus-trap.spec.ts"
   },
   "dependencies": {
     "chokidar": "^4.0.3",
@@ -30,6 +32,7 @@
     "shiki": "^3.2.1"
   },
   "devDependencies": {
+    "@playwright/test": "^1.58.2",
     "@types/markdown-it": "^14.1.2",
     "@types/picomatch": "^4.0.2",
     "bun-types": "^1.3.8"

package/src/build.ts

@@ -19,7 +19,6 @@ import {
   stripMdExt,
   toPosixPath,
   toDocId,
-  toRoute,
 } from "./utils";
 
 const CACHE_VERSION = 3;
@@ -44,6 +43,7 @@ interface RuntimeAssets {
 
 interface WikiLookup {
   byPath: Map<string, DocRecord>;
+  byPrefix: Map<string, DocRecord[]>;
   byStem: Map<string, DocRecord[]>;
 }
 
@@ -364,6 +364,20 @@ function appendRouteSuffix(route: string, suffix: string): string {
   return `/${segments.join("/")}/`;
 }
 
+function toPrefixRoute(prefix: string): string {
+  const normalized = prefix
+    .normalize("NFKC")
+    .trim()
+    .replace(/['’]/g, "")
+    .replace(/[\s_]+/g, "-")
+    .replace(/\//g, "-")
+    .replace(/[^\p{Letter}\p{Number}-]+/gu, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "");
+
+  return `/${normalized || "untitled"}/`;
+}
+
 function ensureUniqueRoutes(docs: DocRecord[]): void {
   const initialBuckets = new Map<string, DocRecord[]>();
   for (const doc of docs) {
@@ -480,7 +494,7 @@ function toDocRecord(
     relPath,
     relNoExt,
     id,
-    route: toRoute(relNoExt),
+    route: toPrefixRoute(entry.prefix ?? ""),
     contentUrl: `/content/${toContentFileName(id)}`,
     fileName,
     title: entry.title ?? makeTitleFromFileName(fileName),
@@ -544,6 +558,11 @@ async function readPublishedDocs(options: BuildOptions, previousSources: BuildCa
     if (!completeEntry.publish || completeEntry.draft) {
       continue;
     }
+
+    if (!completeEntry.prefix) {
+      console.warn(`[publish] Skipped published doc without prefix: ${relPath}`);
+      continue;
+    }
     docs.push(toDocRecord(sourcePath, relPath, completeEntry, newThreshold));
   }
 
@@ -553,25 +572,32 @@ async function readPublishedDocs(options: BuildOptions, previousSources: BuildCa
 
 function createWikiLookup(docs: DocRecord[]): WikiLookup {
   const byPath = new Map<string, DocRecord>();
+  const byPrefix = new Map<string, DocRecord[]>();
   const byStem = new Map<string, DocRecord[]>();
 
   for (const doc of docs) {
     byPath.set(doc.relNoExt.toLowerCase(), doc);
+    if (doc.prefix) {
+      const prefixKey = normalizeWikiTarget(doc.prefix);
+      const prefixBucket = byPrefix.get(prefixKey) ?? [];
+      prefixBucket.push(doc);
+      byPrefix.set(prefixKey, prefixBucket);
+    }
     const stem = path.basename(doc.relNoExt).toLowerCase();
     const bucket = byStem.get(stem) ?? [];
     bucket.push(doc);
     byStem.set(stem, bucket);
   }
 
-  return { byPath, byStem };
+  return { byPath, byPrefix, byStem };
 }
 
-function resolveWikiTarget(
+function resolveWikiTargetDoc(
   lookup: WikiLookup,
   input: string,
   currentDoc: DocRecord,
   warnOnDuplicate: boolean,
-): { route: string; label: string } | null {
+): DocRecord | null {
   const normalized = normalizeWikiTarget(input);
   if (!normalized) {
     return null;
@@ -579,7 +605,21 @@ function resolveWikiTarget(
 
   const direct = lookup.byPath.get(normalized);
   if (direct) {
-    return { route: direct.route, label: direct.title };
+    return direct;
+  }
+
+  const prefixMatches = lookup.byPrefix.get(normalized) ?? [];
+  if (prefixMatches.length === 1) {
+    return prefixMatches[0];
+  }
+
+  if (warnOnDuplicate && prefixMatches.length > 1) {
+    console.warn(
+      `[wikilink] Duplicate prefix target "${input}" in ${currentDoc.relPath}. Candidates: ${prefixMatches
+        .map((item) => item.relPath)
+        .join(", ")}`,
+    );
+    return null;
   }
 
   if (normalized.includes("/")) {
@@ -588,7 +628,7 @@ function resolveWikiTarget(
 
   const stemMatches = lookup.byStem.get(normalized) ?? [];
   if (stemMatches.length === 1) {
-    return { route: stemMatches[0].route, label: stemMatches[0].title };
+    return stemMatches[0];
   }
 
   if (warnOnDuplicate && stemMatches.length > 1) {
@@ -600,6 +640,20 @@ function resolveWikiTarget(
   return null;
 }
 
+function resolveWikiTarget(
+  lookup: WikiLookup,
+  input: string,
+  currentDoc: DocRecord,
+  warnOnDuplicate: boolean,
+): { route: string; label: string } | null {
+  const resolved = resolveWikiTargetDoc(lookup, input, currentDoc, warnOnDuplicate);
+  if (!resolved) {
+    return null;
+  }
+
+  return { route: resolved.route, label: resolved.title };
+}
+
 function createWikiResolver(lookup: WikiLookup, currentDoc: DocRecord): WikiResolver {
   return {
     resolve(input: string) {
@@ -773,6 +827,9 @@ function buildManifest(docs: DocRecord[], tree: TreeNode[], options: BuildOption
     routeMap[doc.route] = doc.id;
   }
 
+  const wikiLookup = createWikiLookup(docs);
+  const backlinksByDocId = buildBacklinksByDocId(docs, wikiLookup);
+
   const docsForManifest = docs.map((doc) => ({
     id: doc.id,
     route: doc.route,
@@ -785,6 +842,8 @@ function buildManifest(docs: DocRecord[], tree: TreeNode[], options: BuildOption
     isNew: doc.isNew,
     contentUrl: doc.contentUrl,
     branch: doc.branch,
+    wikiTargets: doc.wikiTargets,
+    backlinks: backlinksByDocId.get(doc.id) ?? [],
   }));
 
   const branchSet = new Set<string>([DEFAULT_BRANCH]);
@@ -1167,7 +1226,29 @@ function renderInitialNav(docs: DocRecord[], currentId: string): string {
   return html;
 }
 
-function buildInitialView(doc: DocRecord, docs: DocRecord[], contentHtml: string): AppShellInitialView {
+function renderInitialBacklinks(backlinks: Manifest["docs"][number]["backlinks"]): string {
+  if (backlinks.length === 0) {
+    return "";
+  }
+
+  let html = '<h2 class="backlinks-title">Backlinks</h2><ul class="backlinks-list">';
+  for (const backlink of backlinks) {
+    const prefixHtml = backlink.prefix
+      ? `<span class="backlink-prefix">${escapeHtmlAttribute(backlink.prefix)}</span>`
+      : "";
+    html += `<li class="backlinks-item"><a href="${escapeHtmlAttribute(backlink.route)}" class="backlink-link" data-route="${escapeHtmlAttribute(backlink.route)}">${prefixHtml}<span class="backlink-text">${escapeHtmlAttribute(backlink.title)}</span></a></li>`;
+  }
+  html += "</ul>";
+  return html;
+}
+
+function buildInitialView(
+  doc: DocRecord,
+  docs: DocRecord[],
+  contentHtml: string,
+  manifestDocById: Map<string, Manifest["docs"][number]>,
+): AppShellInitialView {
+  const manifestDoc = manifestDocById.get(doc.id);
   return {
     route: doc.route,
     docId: doc.id,
@@ -1175,6 +1256,7 @@ function buildInitialView(doc: DocRecord, docs: DocRecord[], contentHtml: string
     breadcrumbHtml: renderInitialBreadcrumb(doc.route),
     metaHtml: renderInitialMeta(doc),
     contentHtml,
+    backlinksHtml: renderInitialBacklinks(manifestDoc?.backlinks ?? []),
     navHtml: renderInitialNav(docs, doc.id),
   };
 }
@@ -1187,9 +1269,12 @@ async function writeShellPages(
   runtimeAssets: RuntimeAssets,
   contentByDocId: Map<string, string>,
 ): Promise<void> {
+  const manifestDocById = new Map(manifest.docs.map((doc) => [doc.id, doc]));
   const indexDoc = pickHomeDoc(docs);
   const indexOutputPath = "index.html";
-  const indexInitialView = indexDoc ? buildInitialView(indexDoc, docs, contentByDocId.get(indexDoc.id) ?? "") : null;
+  const indexInitialView = indexDoc
+    ? buildInitialView(indexDoc, docs, contentByDocId.get(indexDoc.id) ?? "", manifestDocById)
+    : null;
   const shell = renderAppShellHtml(
     buildShellMeta("/", null, options),
     buildAppShellAssetsForOutput(indexOutputPath, runtimeAssets),
@@ -1206,7 +1291,7 @@ async function writeShellPages(
 
   for (const doc of docs) {
     const routeOutputPath = toRouteOutputPath(doc.route);
-    const initialView = buildInitialView(doc, docs, contentByDocId.get(doc.id) ?? "");
+    const initialView = buildInitialView(doc, docs, contentByDocId.get(doc.id) ?? "", manifestDocById);
     await writeOutputIfChanged(
       context,
       routeOutputPath,
@@ -1311,6 +1396,41 @@ function buildWikiResolutionSignature(doc: DocRecord, lookup: WikiLookup): strin
   return segments.join("|");
 }
 
+function buildBacklinksByDocId(
+  docs: DocRecord[],
+  lookup: WikiLookup,
+): Map<string, Manifest["docs"][number]["backlinks"]> {
+  const buckets = new Map<string, Map<string, Manifest["docs"][number]["backlinks"][number]>>();
+
+  for (const doc of docs) {
+    for (const target of doc.wikiTargets) {
+      const targetDoc = resolveWikiTargetDoc(lookup, target, doc, false);
+      if (!targetDoc || targetDoc.id === doc.id) {
+        continue;
+      }
+
+      const bucket = buckets.get(targetDoc.id) ?? new Map<string, Manifest["docs"][number]["backlinks"][number]>();
+      bucket.set(doc.id, {
+        id: doc.id,
+        route: doc.route,
+        title: doc.title,
+        prefix: doc.prefix,
+      });
+      buckets.set(targetDoc.id, bucket);
+    }
+  }
+
+  const backlinksByDocId = new Map<string, Manifest["docs"][number]["backlinks"]>();
+  for (const doc of docs) {
+    const source = buckets.get(doc.id) ?? new Map<string, Manifest["docs"][number]["backlinks"][number]>();
+    const backlinks = Array.from(source.values()).sort((left, right) =>
+      left.route.localeCompare(right.route, "ko-KR"),
+    );
+    backlinksByDocId.set(doc.id, backlinks);
+  }
+  return backlinksByDocId;
+}
+
 export async function buildSite(options: BuildOptions): Promise<BuildResult> {
   await ensureDir(options.outDir);
   await ensureDir(path.join(options.outDir, "content"));

package/src/runtime/app.css

@@ -1168,6 +1168,62 @@ body.mobile-toggle-left .mobile-menu-toggle {
   border-top: 1px solid var(--latte-surface0);
 }
 
+.viewer-backlinks {
+  margin-top: 44px;
+  padding-top: 28px;
+  border-top: 1px solid var(--latte-surface0);
+}
+
+.backlinks-title {
+  margin: 0 0 14px;
+  font-size: 1.05rem;
+  color: var(--latte-subtext0);
+}
+
+.backlinks-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: grid;
+  gap: 10px;
+}
+
+.backlinks-item {
+  margin: 0;
+}
+
+.backlink-link {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  text-decoration: none;
+  color: var(--latte-text);
+  padding: 8px 10px;
+  border: 1px solid var(--latte-surface0);
+  border-radius: 8px;
+  background: var(--active-surface-bg);
+  transition: border-color 0.15s ease, color 0.15s ease;
+}
+
+.backlink-link:hover {
+  border-color: var(--latte-mauve);
+  color: var(--latte-mauve);
+}
+
+.backlink-prefix {
+  font-size: 0.72rem;
+  font-weight: 700;
+  letter-spacing: 0.03em;
+  color: var(--latte-overlay0);
+  padding: 1px 7px;
+  border-radius: 999px;
+  border: 1px solid var(--latte-surface0);
+}
+
+.backlink-text {
+  font-size: 0.9rem;
+}
+
 .nav-link {
   flex: 1;
   padding: 16px;
@@ -1295,12 +1351,17 @@ body.mobile-toggle-left .mobile-menu-toggle {
     border-bottom: 0;
     box-shadow: var(--sidebar-mobile-shadow);
     transform: translateX(-102%);
-    transition: transform 0.2s ease;
+    transition: transform 0.2s ease, visibility 0.2s step-end;
+    visibility: hidden;
+    pointer-events: none;
     z-index: 100;
   }
 
   .app-root.sidebar-open .sidebar {
     transform: translateX(0);
+    visibility: visible;
+    pointer-events: auto;
+    transition: transform 0.2s ease, visibility 0s;
   }
 
   .mobile-menu-toggle {

package/src/runtime/app.js

@@ -229,6 +229,7 @@ function buildBranchView(manifest, branch, defaultBranch) {
 
   return {
     docs,
+    visibleDocIds,
     tree,
     routeMap,
     docIndexById,
@@ -342,7 +343,25 @@ function getFocusableElements(container) {
     if (!(el instanceof HTMLElement)) {
       return false;
     }
-    return !el.hasAttribute("hidden") && el.getAttribute("aria-hidden") !== "true";
+
+    if (el.hasAttribute("hidden") || el.getAttribute("aria-hidden") === "true") {
+      return false;
+    }
+
+    if (el.closest("[hidden], [inert], [aria-hidden='true']")) {
+      return false;
+    }
+
+    if (el instanceof HTMLInputElement && el.type === "hidden") {
+      return false;
+    }
+
+    const style = window.getComputedStyle(el);
+    if (style.display === "none" || style.visibility === "hidden") {
+      return false;
+    }
+
+    return el.getClientRects().length > 0;
   });
 }
 
@@ -758,6 +777,25 @@ function renderNav(docs, docIndexById, currentId) {
   return html;
 }
 
+function renderBacklinks(doc) {
+  const backlinks = Array.isArray(doc.backlinks) ? doc.backlinks : [];
+  if (backlinks.length === 0) {
+    return "";
+  }
+
+  let html = '<h2 class="backlinks-title">Backlinks</h2><ul class="backlinks-list">';
+  for (const backlink of backlinks) {
+    const prefix = typeof backlink.prefix === "string" && backlink.prefix.trim().length > 0
+      ? `<span class="backlink-prefix">${escapeHtmlAttr(backlink.prefix.trim())}</span>`
+      : "";
+    const route = typeof backlink.route === "string" ? normalizeRoute(backlink.route) : "/";
+    const title = typeof backlink.title === "string" && backlink.title.trim().length > 0 ? backlink.title : route;
+    html += `<li class="backlinks-item"><a href="${toSafeUrlPath(route)}" class="backlink-link" data-route="${escapeHtmlAttr(route)}">${prefix}<span class="backlink-text">${escapeHtmlAttr(title)}</span></a></li>`;
+  }
+  html += "</ul>";
+  return html;
+}
+
 async function start() {
   const treeRoot = document.getElementById("tree-root");
   const appRoot = document.querySelector(".app-root");
@@ -778,6 +816,7 @@ async function start() {
   const titleEl = document.getElementById("viewer-title");
   const metaEl = document.getElementById("viewer-meta");
   const contentEl = document.getElementById("viewer-content");
+  const backlinksEl = document.getElementById("viewer-backlinks");
   const navEl = document.getElementById("viewer-nav");
   const a11yStatusEl = document.getElementById("a11y-status");
   const viewerEl = document.querySelector(".viewer");
@@ -897,24 +936,56 @@ async function start() {
     closeSettings();
   };
 
+  const setViewerInteractiveState = (isInteractive) => {
+    if (!(viewerEl instanceof HTMLElement)) {
+      return;
+    }
+
+    if (isInteractive) {
+      viewerEl.removeAttribute("inert");
+      viewerEl.removeAttribute("aria-hidden");
+      return;
+    }
+
+    viewerEl.setAttribute("inert", "");
+    viewerEl.setAttribute("aria-hidden", "true");
+  };
+
   const syncSidebarA11y = (isOpen) => {
     if (sidebarToggle) {
       sidebarToggle.setAttribute("aria-expanded", String(isOpen));
     }
 
-    if (!sidebar) {
+    if (sidebarOverlay) {
+      sidebarOverlay.setAttribute("aria-hidden", String(!isOpen));
+    }
+
+    if (!(sidebar instanceof HTMLElement)) {
+      setViewerInteractiveState(true);
       return;
     }
 
     if (!isCompactLayout()) {
       sidebar.removeAttribute("inert");
+      sidebar.removeAttribute("aria-hidden");
+      sidebar.removeAttribute("aria-modal");
+      sidebar.setAttribute("role", "complementary");
+      setViewerInteractiveState(true);
       return;
     }
 
     if (isOpen) {
       sidebar.removeAttribute("inert");
+      sidebar.removeAttribute("aria-hidden");
+      sidebar.setAttribute("role", "dialog");
+      sidebar.setAttribute("aria-modal", "true");
+      setViewerInteractiveState(false);
     } else {
       sidebar.setAttribute("inert", "");
+      sidebar.setAttribute("aria-hidden", "true");
+      sidebar.removeAttribute("aria-modal");
+      sidebar.setAttribute("role", "complementary");
+      setViewerInteractiveState(true);
     }
   };
 
@@ -1253,6 +1324,20 @@ async function start() {
     markActive(treeFileRowsById, activeFileState, state.currentDocId || "");
   };
 
+  const updateBacklinks = (doc) => {
+    if (!(backlinksEl instanceof HTMLElement)) {
+      return;
+    }
+    if (!doc) {
+      backlinksEl.innerHTML = "";
+      backlinksEl.hidden = true;
+      return;
+    }
+    const html = renderBacklinks(doc);
+    backlinksEl.innerHTML = html;
+    backlinksEl.hidden = html.length === 0;
+  };
+
   const state = {
     expanded,
     currentDocId: initialViewData?.docId ?? "",
@@ -1270,8 +1355,9 @@ async function start() {
         const globalId = manifest.routeMap?.[route];
         const globalDoc = globalId ? docsById.get(globalId) : null;
         const globalDocBranch = normalizeBranch(globalDoc?.branch);
-        if (globalDoc && globalDocBranch && globalDocBranch !== activeBranch && availableBranchSet.has(globalDocBranch)) {
-          activeBranch = globalDocBranch;
+        const targetBranch = globalDocBranch ?? defaultBranch;
+        if (globalDoc && targetBranch !== activeBranch && availableBranchSet.has(targetBranch)) {
+          activeBranch = targetBranch;
           view = getBranchView(activeBranch);
           updateBranchInfo();
           renderTree(state);
@@ -1286,6 +1372,7 @@ async function start() {
         titleEl.textContent = "문서를 찾을 수 없습니다";
         metaEl.innerHTML = "";
         contentEl.innerHTML = '<p class="placeholder">요청한 경로에 해당하는 문서가 없습니다.</p>';
+        updateBacklinks(null);
         navEl.innerHTML = "";
         markActive(treeFileRowsById, activeFileState, "");
         announceA11yStatus("탐색 실패: 요청한 문서를 찾을 수 없습니다.");
@@ -1315,7 +1402,12 @@ async function start() {
 
       if (shouldUseInitialView) {
         hasHydratedInitialView = true;
-        document.title = composeDocumentTitle(initialViewData.title, siteTitle);
+        breadcrumbEl.innerHTML = renderBreadcrumb(route);
+        titleEl.textContent = doc.title;
+        metaEl.innerHTML = renderMeta(doc);
+        updateBacklinks(doc);
+        navEl.innerHTML = renderNav(view.docs, view.docIndexById, id);
+        document.title = composeDocumentTitle(doc.title, siteTitle);
         if (viewerEl instanceof HTMLElement) {
           viewerEl.scrollTo(0, 0);
         }
@@ -1330,6 +1422,7 @@ async function start() {
       const res = await fetch(toSafeUrlPath(doc.contentUrl));
       if (!res.ok) {
         contentEl.innerHTML = '<p class="placeholder">본문을 불러오지 못했습니다.</p>';
+        updateBacklinks(null);
         navEl.innerHTML = "";
         announceA11yStatus(`탐색 실패: ${doc.title} 문서를 불러오지 못했습니다.`);
         return;
@@ -1337,6 +1430,7 @@ async function start() {
 
       contentEl.innerHTML = await res.text();
 
+      updateBacklinks(doc);
       navEl.innerHTML = renderNav(view.docs, view.docIndexById, id);
 
       document.title = composeDocumentTitle(doc.title, siteTitle);
@@ -1462,6 +1556,30 @@ async function start() {
     });
   }
 
+  if (backlinksEl instanceof HTMLElement) {
+    backlinksEl.addEventListener("click", (event) => {
+      const target = event.target;
+      if (!(target instanceof Element)) {
+        return;
+      }
+
+      const link = target.closest(".backlink-link");
+      if (!(link instanceof HTMLAnchorElement) || !backlinksEl.contains(link)) {
+        return;
+      }
+
+      event.preventDefault();
+      const route = link.dataset.route;
+      if (!route) {
+        return;
+      }
+      state.navigate(route, true);
+      if (viewerEl instanceof HTMLElement) {
+        viewerEl.scrollTo(0, 0);
+      }
+    });
+  }
+
   initializeTreeTypeahead(treeRoot);
 
   const setActiveBranch = async (nextBranch) => {

package/src/template.ts

@@ -36,6 +36,7 @@ export interface AppShellInitialView {
   breadcrumbHtml: string;
   metaHtml: string;
   contentHtml: string;
+  backlinksHtml: string;
   navHtml: string;
 }
 
@@ -192,6 +193,7 @@ export function renderAppShellHtml(
   const initialContent = initialView
     ? initialView.contentHtml
     : '<p class="placeholder">좌측 탐색기에서 문서를 선택하세요.</p>';
+  const initialBacklinks = initialView ? initialView.backlinksHtml : "";
   const initialNav = initialView ? initialView.navHtml : "";
 
   return `<!doctype html>
@@ -211,8 +213,8 @@ ${headMeta}
     <a class="skip-link" href="#viewer-panel">본문으로 건너뛰기</a>
     <div id="a11y-status" class="sr-only" aria-live="polite" aria-atomic="true"></div>
     <div class="app-root">
-      <div id="sidebar-overlay" class="sidebar-overlay" hidden></div>
-      <aside id="sidebar-panel" class="sidebar" aria-label="문서 탐색기 패널">
+      <div id="sidebar-overlay" class="sidebar-overlay" aria-hidden="true" hidden></div>
+      <aside id="sidebar-panel" class="sidebar" role="complementary" aria-label="문서 탐색기 패널">
         <div class="sidebar-header">
           <h1 class="sidebar-title">
             <span class="material-symbols-outlined icon-terminal">terminal</span>
@@ -310,6 +312,7 @@ ${headMeta}
             <div id="viewer-meta" class="viewer-meta">${initialMeta}</div>
           </header>
           <article id="viewer-content" class="viewer-content">${initialContent}</article>
+          <section id="viewer-backlinks" class="viewer-backlinks" aria-label="문서를 참조한 링크" ${initialBacklinks ? "" : "hidden"}>${initialBacklinks}</section>
           <nav id="viewer-nav" class="viewer-nav" aria-label="문서 이전/다음 탐색">${initialNav}</nav>
         </div>
       </main>

package/src/types.ts

@@ -147,6 +147,13 @@ export interface Manifest {
     description?: string;
     isNew: boolean;
     branch: string | null;
+    wikiTargets: string[];
+    backlinks: Array<{
+      id: string;
+      route: string;
+      title: string;
+      prefix?: string;
+    }>;
   }>;
 }