@limcpf/everything-is-a-markdown 0.3.0 → 0.4.0

package/README.md

@@ -65,7 +65,7 @@ bun run blog [build|dev|clean] [options]
 - `--exclude <glob>`: 제외 패턴 (반복 가능, 기본 포함: `.obsidian/**`)
 - `--new-within-days <n>`: NEW 배지 기준 일수 (기본: `7`)
 - `--recent-limit <n>`: Recent 가상 폴더 노출 개수 (기본: `5`)
-- `--menu-config <path>`: 상단 고정 메뉴(JSON) 설정 파일 경로
+- `--menu-config <path>`: 상단 고정 메뉴를 JSON 파일로 임시 덮어쓰기(선택)
 - `--port <n>`: dev 서버 포트 (기본: `3000`)
 
 **릴리즈 단일파일 배포 (GitHub Actions)**
@@ -106,22 +106,10 @@ bun run dev -- --port 4000
 # 제외 패턴 추가
 bun run build -- --exclude "private/**" --exclude "**/drafts/**"
 
-# 상단 고정 메뉴 추가
+# 상단 고정 메뉴 임시 덮어쓰기(선택)
 bun run build -- --menu-config ./menu.config.json
 ```
 
-고정 메뉴 설정 파일 예시 (`menu.config.json`)
-```json
-{
-  "pinnedMenu": {
-    "label": "NOTICE",
-    "sourceDir": "Log/(Blog)/Notice"
-  }
-}
-```
-- `label`: 탐색기에서 Recent 위에 표시할 고정 메뉴 이름
-- `sourceDir`: vault 기준 실제 물리 디렉터리 경로 (해당 하위 문서만 고정 메뉴에 노출)
-
 **설정 파일**
 프로젝트 루트에 `blog.config.ts|js|mjs|cjs`를 두면 CLI 옵션과 병합됩니다.
 
@@ -134,11 +122,25 @@ export default {
   seo: {
     siteUrl: "https://example.com", // origin only (http/https)
     pathBase: "/blog", // optional, deploy base path
+    siteName: "Everything-Is-A-Markdown", // optional, og:site_name / WebSite.name
+    defaultTitle: "Dev Knowledge Base", // optional, fallback title
+    defaultDescription: "Public docs and engineering notes.", // optional, fallback description
+    locale: "ko_KR", // optional, og:locale
+    twitterCard: "summary_large_image", // optional: "summary" | "summary_large_image"
+    twitterSite: "@my_team", // optional
+    twitterCreator: "@author_handle", // optional
+    defaultSocialImage: "/assets/social/default.png", // optional, absolute URL or /-relative
+    defaultOgImage: "/assets/social/og.png", // optional, overrides defaultSocialImage for og:image
+    defaultTwitterImage: "/assets/social/twitter.png", // optional, overrides defaultSocialImage for twitter:image
   },
   ui: {
     newWithinDays: 7,
     recentLimit: 5,
   },
+  pinnedMenu: {
+    label: "NOTICE",
+    sourceDir: "Log/(Blog)/Notice",
+  },
   markdown: {
     wikilinks: true,
     images: "omit-local", // "keep" | "omit-local"
@@ -150,9 +152,22 @@ export default {
 };
 ```
 
+고정 메뉴 설정 메모
+- `pinnedMenu.label`: 탐색기에서 Recent 위에 표시할 이름 (미지정 시 `NOTICE`)
+- `pinnedMenu.sourceDir`: vault 기준 실제 물리 디렉터리 경로
+- `--menu-config`를 주면 `blog.config.*`의 `pinnedMenu`를 해당 실행에서만 덮어씁니다.
+
 SEO 설정 메모
 - `seo.siteUrl`: 필수. 절대 origin만 허용됩니다 (예: `https://example.com`, path/query/hash 불가).
 - `seo.pathBase`: 선택. `/blog` 같은 배포 base path를 canonical/OG/sitemap URL에 함께 붙입니다.
+- `seo.siteName`: 선택. `og:site_name` 및 루트 JSON-LD(WebSite.name)에 반영됩니다.
+- `seo.defaultTitle`: 선택. 문서 제목이 없을 때 fallback `<title>`로 사용됩니다.
+- `seo.defaultDescription`: 선택. 문서 설명이 없을 때 fallback description/OG/Twitter 설명으로 사용됩니다.
+- `seo.locale`: 선택. `og:locale` 값으로 출력됩니다 (예: `ko_KR`).
+- `seo.twitterCard`: 선택. `summary` 또는 `summary_large_image`.
+- `seo.twitterSite`, `seo.twitterCreator`: 선택. 각각 `twitter:site`, `twitter:creator`로 출력됩니다.
+- `seo.defaultSocialImage`: 선택. OG/Twitter 공통 기본 이미지.
+- `seo.defaultOgImage`, `seo.defaultTwitterImage`: 선택. 채널별 이미지 우선값(없으면 `defaultSocialImage` 사용).
 - `seo.siteUrl`이 없으면 `robots.txt`, `sitemap.xml`은 생성되지 않습니다.
 
 **콘텐츠 작성 규칙**

package/bun.lock

@@ -1,5 +1,6 @@
 {
   "lockfileVersion": 1,
+  "configVersion": 0,
   "workspaces": {
     "": {
       "name": "@limcpf/everything-is-a-markdown",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@limcpf/everything-is-a-markdown",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "private": false,
   "type": "module",
   "bin": {

package/src/build.ts

@@ -3,9 +3,9 @@ import path from "node:path";
 import matter from "gray-matter";
 import type { BuildCache, BuildOptions, DocRecord, FileNode, FolderNode, Manifest, TreeNode, WikiResolver } from "./types";
 import { createMarkdownRenderer } from "./markdown";
-import { buildCanonicalUrl } from "./seo";
+import { buildCanonicalUrl, escapeHtmlAttribute } from "./seo";
 import { render404Html, renderAppShellHtml } from "./template";
-import type { AppShellMeta } from "./template";
+import type { AppShellAssets, AppShellInitialView, AppShellMeta } from "./template";
 import {
   buildExcluder,
   ensureDir,
@@ -35,6 +35,11 @@ interface OutputWriteContext {
   nextHashes: Record<string, string>;
 }
 
+interface RuntimeAssets {
+  cssRelPath: string;
+  jsRelPath: string;
+}
+
 interface WikiLookup {
   byPath: Map<string, DocRecord>;
   byStem: Map<string, DocRecord[]>;
@@ -393,9 +398,11 @@ function normalizeWikiTarget(input: string): string {
 function extractWikiTargets(markdown: string): string[] {
   const targets = new Set<string>();
   const re = /\[\[([^\]]+)\]\]/g;
-  let match: RegExpExecArray | null;
-
-  while ((match = re.exec(markdown)) !== null) {
+  while (true) {
+    const match = re.exec(markdown);
+    if (match === null) {
+      break;
+    }
     if (match.index > 0 && markdown.charAt(match.index - 1) === "!") {
       continue;
     }
@@ -410,7 +417,6 @@ function extractWikiTargets(markdown: string): string[] {
     if (!normalized) {
       continue;
     }
-
     targets.add(normalized);
   }
 
@@ -462,7 +468,7 @@ function toDocRecord(
     body: entry.body,
     rawHash: entry.rawHash,
     wikiTargets: entry.wikiTargets,
-    isNew: entry.mtimeMs >= newThreshold,
+    isNew: isNewByFrontmatterDate(entry.date, newThreshold),
     branch: entry.branch,
   };
 }
@@ -621,6 +627,11 @@ function parseDateToEpochMs(value: string | undefined): number | null {
   return Number.isFinite(parsed) ? parsed : null;
 }
 
+function isNewByFrontmatterDate(date: string | undefined, newThreshold: number): boolean {
+  const publishedAt = parseDateToEpochMs(date);
+  return publishedAt != null && publishedAt >= newThreshold;
+}
+
 function getRecentSortEpochMs(doc: DocRecord): number {
   return parseDateToEpochMs(doc.date) ?? doc.mtimeMs;
 }
@@ -778,12 +789,6 @@ function pickSeoImageDefaults(
     return { social: null, og: null, twitter: null };
   }
 
-  const raw = seo as BuildOptions["seo"] & {
-    defaultSocialImage?: unknown;
-    defaultOgImage?: unknown;
-    defaultTwitterImage?: unknown;
-  };
-
   const toAbsoluteImage = (value: unknown): string | null => {
     if (typeof value !== "string") {
       return null;
@@ -804,20 +809,21 @@ function pickSeoImageDefaults(
   };
 
   return {
-    social: toAbsoluteImage(raw.defaultSocialImage),
-    og: toAbsoluteImage(raw.defaultOgImage),
-    twitter: toAbsoluteImage(raw.defaultTwitterImage),
+    social: toAbsoluteImage(seo.defaultSocialImage),
+    og: toAbsoluteImage(seo.defaultOgImage),
+    twitter: toAbsoluteImage(seo.defaultTwitterImage),
   };
 }
 
 function buildStructuredData(route: string, doc: DocRecord | null, options: BuildOptions): unknown[] {
   const canonicalUrl = options.seo ? buildCanonicalUrl(route, options.seo) : undefined;
+  const siteName = options.seo?.siteName ?? options.seo?.defaultTitle ?? DEFAULT_SITE_TITLE;
 
   if (!doc) {
     const websiteSchema: Record<string, string> = {
       "@context": "https://schema.org",
       "@type": "WebSite",
-      name: DEFAULT_SITE_TITLE,
+      name: siteName,
     };
     if (canonicalUrl) {
       websiteSchema.url = canonicalUrl;
@@ -865,19 +871,54 @@ async function writeOutputIfChanged(
   await Bun.write(outputPath, content);
 }
 
-async function writeRuntimeAssets(context: OutputWriteContext): Promise<void> {
+function toRelativeAssetPath(fromOutputPath: string, assetOutputPath: string): string {
+  const fromDir = path.posix.dirname(fromOutputPath);
+  const relative = path.posix.relative(fromDir, assetOutputPath);
+  return relative.length > 0 ? relative : path.posix.basename(assetOutputPath);
+}
+
+function buildAppShellAssetsForOutput(outputPath: string, runtimeAssets: RuntimeAssets): AppShellAssets {
+  return {
+    cssHref: toRelativeAssetPath(outputPath, runtimeAssets.cssRelPath),
+    jsSrc: toRelativeAssetPath(outputPath, runtimeAssets.jsRelPath),
+  };
+}
+
+async function writeRuntimeAssets(context: OutputWriteContext): Promise<RuntimeAssets> {
   const runtimeDir = path.join(import.meta.dir, "runtime");
   const runtimeJs = await Bun.file(path.join(runtimeDir, "app.js")).text();
   const runtimeCss = await Bun.file(path.join(runtimeDir, "app.css")).text();
 
-  await writeOutputIfChanged(context, "assets/app.js", runtimeJs);
-  await writeOutputIfChanged(context, "assets/app.css", runtimeCss);
+  const jsRelPath = `assets/app.${makeHash(runtimeJs).slice(0, 12)}.js`;
+  const cssRelPath = `assets/app.${makeHash(runtimeCss).slice(0, 12)}.css`;
+
+  for (const previousPath of Object.keys(context.previousHashes)) {
+    const isLegacyRuntimeAsset =
+      previousPath.startsWith("assets/app") &&
+      (previousPath.endsWith(".js") || previousPath.endsWith(".css")) &&
+      previousPath !== jsRelPath &&
+      previousPath !== cssRelPath;
+    if (!isLegacyRuntimeAsset) {
+      continue;
+    }
+    await removeFileIfExists(path.join(context.outDir, previousPath));
+  }
+
+  await writeOutputIfChanged(context, jsRelPath, runtimeJs);
+  await writeOutputIfChanged(context, cssRelPath, runtimeCss);
+
+  return {
+    cssRelPath,
+    jsRelPath,
+  };
 }
 
 function buildShellMeta(route: string, doc: DocRecord | null, options: BuildOptions): AppShellMeta {
+  const defaultTitle = options.seo?.defaultTitle ?? DEFAULT_SITE_TITLE;
+  const defaultDescription = options.seo?.defaultDescription ?? DEFAULT_SITE_DESCRIPTION;
   const description = typeof doc?.description === "string" && doc.description.trim().length > 0 ? doc.description.trim() : undefined;
   const canonicalUrl = options.seo ? buildCanonicalUrl(route, options.seo) : undefined;
-  const title = doc?.title ?? DEFAULT_SITE_TITLE;
+  const title = doc?.title ?? defaultTitle;
   const imageDefaults = pickSeoImageDefaults(options.seo);
   const ogImage = imageDefaults.og ?? imageDefaults.social ?? undefined;
   const twitterImage = imageDefaults.twitter ?? imageDefaults.social ?? undefined;
@@ -888,28 +929,150 @@ function buildShellMeta(route: string, doc: DocRecord | null, options: BuildOpti
     canonicalUrl,
     ogTitle: title,
     ogType: doc ? "article" : "website",
+    ogSiteName: options.seo?.siteName,
+    ogLocale: options.seo?.locale,
     ogUrl: canonicalUrl,
-    ogDescription: description ?? DEFAULT_SITE_DESCRIPTION,
-    twitterCard: "summary",
+    ogDescription: description ?? defaultDescription,
+    twitterCard: options.seo?.twitterCard ?? "summary",
     twitterTitle: title,
-    twitterDescription: description ?? DEFAULT_SITE_DESCRIPTION,
+    twitterDescription: description ?? defaultDescription,
+    twitterSite: options.seo?.twitterSite,
+    twitterCreator: options.seo?.twitterCreator,
     ogImage,
     twitterImage,
     jsonLd: buildStructuredData(route, doc, options),
   };
 }
 
-async function writeShellPages(context: OutputWriteContext, docs: DocRecord[], options: BuildOptions): Promise<void> {
-  const shell = renderAppShellHtml(buildShellMeta("/", null, options));
+function renderInitialBreadcrumb(route: string): string {
+  const parts = route.split("/").filter(Boolean);
+  const allItems = ["~", ...parts];
+  return allItems
+    .map((part, index) => {
+      const isCurrent = index === allItems.length - 1 && allItems.length > 1;
+      const escapedPart = escapeHtmlAttribute(part);
+      if (isCurrent) {
+        return `<span class="breadcrumb-current" aria-current="page">${escapedPart}</span>`;
+      }
+      return `<span class="breadcrumb-item">${escapedPart}</span>`;
+    })
+    .join('<span class="material-symbols-outlined breadcrumb-sep">chevron_right</span>');
+}
+
+function formatMetaDateTime(value: string | undefined): string | null {
+  if (!value) {
+    return null;
+  }
+
+  const parsed = new Date(value);
+  if (!Number.isFinite(parsed.getTime())) {
+    return null;
+  }
+
+  const yyyy = parsed.getFullYear();
+  const mm = String(parsed.getMonth() + 1).padStart(2, "0");
+  const dd = String(parsed.getDate()).padStart(2, "0");
+  const hh = String(parsed.getHours()).padStart(2, "0");
+  const mi = String(parsed.getMinutes()).padStart(2, "0");
+  return `${yyyy}-${mm}-${dd} ${hh}:${mi}`;
+}
+
+function normalizeTags(tags: string[]): string[] {
+  return tags.map((tag) => String(tag).trim().replace(/^#+/, "")).filter(Boolean);
+}
+
+function renderInitialMeta(doc: DocRecord): string {
+  const items: string[] = [];
+
+  const createdAt = formatMetaDateTime(doc.date);
+  if (createdAt) {
+    items.push(
+      `<span class="meta-item"><span class="material-symbols-outlined">calendar_today</span>${escapeHtmlAttribute(createdAt)}</span>`,
+    );
+  }
+
+  const updatedAt = formatMetaDateTime(doc.updatedDate);
+  if (updatedAt) {
+    items.push(
+      `<span class="meta-item"><span class="material-symbols-outlined">schedule</span>updated ${escapeHtmlAttribute(updatedAt)}</span>`,
+    );
+  }
+
+  const tags = normalizeTags(doc.tags);
+  if (tags.length > 0) {
+    const tagsStr = tags.map((tag) => `#${escapeHtmlAttribute(tag)}`).join(" ");
+    items.push(`<span class="meta-item meta-tags">${tagsStr}</span>`);
+  }
+
+  return items.join("");
+}
+
+function renderInitialNav(docs: DocRecord[], currentId: string): string {
+  const currentIndex = docs.findIndex((doc) => doc.id === currentId);
+  if (currentIndex === -1) {
+    return "";
+  }
+
+  const prev = currentIndex > 0 ? docs[currentIndex - 1] : null;
+  const next = currentIndex < docs.length - 1 ? docs[currentIndex + 1] : null;
+
+  let html = "";
+  if (prev) {
+    html += `<a href="${escapeHtmlAttribute(prev.route)}" class="nav-link nav-link-prev" data-route="${escapeHtmlAttribute(prev.route)}"><div class="nav-link-label"><span class="material-symbols-outlined">arrow_back</span>Previous</div><div class="nav-link-title">${escapeHtmlAttribute(prev.title)}</div></a>`;
+  }
+  if (next) {
+    html += `<a href="${escapeHtmlAttribute(next.route)}" class="nav-link nav-link-next" data-route="${escapeHtmlAttribute(next.route)}"><div class="nav-link-label">Next<span class="material-symbols-outlined">arrow_forward</span></div><div class="nav-link-title">${escapeHtmlAttribute(next.title)}</div></a>`;
+  }
+
+  return html;
+}
+
+function buildInitialView(doc: DocRecord, docs: DocRecord[], contentHtml: string): AppShellInitialView {
+  return {
+    route: doc.route,
+    docId: doc.id,
+    title: doc.title,
+    breadcrumbHtml: renderInitialBreadcrumb(doc.route),
+    metaHtml: renderInitialMeta(doc),
+    contentHtml,
+    navHtml: renderInitialNav(docs, doc.id),
+  };
+}
+
+async function writeShellPages(
+  context: OutputWriteContext,
+  docs: DocRecord[],
+  options: BuildOptions,
+  runtimeAssets: RuntimeAssets,
+  contentByDocId: Map<string, string>,
+): Promise<void> {
+  const indexDoc = docs[0] ?? null;
+  const indexOutputPath = "index.html";
+  const indexInitialView = indexDoc ? buildInitialView(indexDoc, docs, contentByDocId.get(indexDoc.id) ?? "") : null;
+  const shell = renderAppShellHtml(
+    buildShellMeta("/", null, options),
+    buildAppShellAssetsForOutput(indexOutputPath, runtimeAssets),
+    indexInitialView,
+  );
   await writeOutputIfChanged(context, "_app/index.html", shell);
-  await writeOutputIfChanged(context, "index.html", shell);
-  await writeOutputIfChanged(context, "404.html", render404Html());
+  await writeOutputIfChanged(context, indexOutputPath, shell);
+  await writeOutputIfChanged(
+    context,
+    "404.html",
+    render404Html(buildAppShellAssetsForOutput("404.html", runtimeAssets)),
+  );
 
   for (const doc of docs) {
+    const routeOutputPath = toRouteOutputPath(doc.route);
+    const initialView = buildInitialView(doc, docs, contentByDocId.get(doc.id) ?? "");
     await writeOutputIfChanged(
       context,
-      toRouteOutputPath(doc.route),
-      renderAppShellHtml(buildShellMeta(doc.route, doc, options)),
+      routeOutputPath,
+      renderAppShellHtml(
+        buildShellMeta(doc.route, doc, options),
+        buildAppShellAssetsForOutput(routeOutputPath, runtimeAssets),
+        initialView,
+      ),
     );
   }
 }
@@ -1023,17 +1186,15 @@ export async function buildSite(options: BuildOptions): Promise<BuildResult> {
     previousHashes: previousOutputHashes,
     nextHashes: {},
   };
-  await writeRuntimeAssets(outputContext);
+  const runtimeAssets = await writeRuntimeAssets(outputContext);
 
   const tree = buildTree(docs, options);
   const manifest = buildManifest(docs, tree, options);
   await writeOutputIfChanged(outputContext, "manifest.json", `${JSON.stringify(manifest, null, 2)}\n`);
 
-  await writeShellPages(outputContext, docs, options);
-  await writeSeoArtifacts(outputContext, docs, options);
-
   const markdownRenderer = await createMarkdownRenderer(options);
   const wikiLookup = createWikiLookup(docs);
+  const contentByDocId = new Map<string, string>();
 
   let renderedDocs = 0;
   let skippedDocs = 0;
@@ -1071,6 +1232,14 @@ export async function buildSite(options: BuildOptions): Promise<BuildResult> {
 
     if (unchanged) {
       skippedDocs += 1;
+      const outputFile = Bun.file(outputPath);
+      if (await outputFile.exists()) {
+        contentByDocId.set(doc.id, await outputFile.text());
+      } else {
+        const resolver = createWikiResolver(wikiLookup, doc);
+        const renderResult = await markdownRenderer.render(doc.body, resolver);
+        contentByDocId.set(doc.id, renderResult.html);
+      }
       continue;
     }
 
@@ -1083,9 +1252,13 @@ export async function buildSite(options: BuildOptions): Promise<BuildResult> {
     }
 
     await Bun.write(outputPath, renderResult.html);
+    contentByDocId.set(doc.id, renderResult.html);
     renderedDocs += 1;
   }
 
+  await writeShellPages(outputContext, docs, options, runtimeAssets, contentByDocId);
+  await writeSeoArtifacts(outputContext, docs, options);
+
   await writeCache(cachePath, nextCache);
 
   return {

package/src/config.ts

@@ -96,12 +96,12 @@ export async function loadUserConfig(cwd = process.cwd()): Promise<UserConfig> {
   return {};
 }
 
-function normalizePinnedMenu(raw: unknown): PinnedMenuOption | null {
+function normalizePinnedMenu(raw: unknown, errorPrefix = "[config]"): PinnedMenuOption | null {
   if (raw == null) {
     return null;
   }
   if (typeof raw !== "object") {
-    throw new Error(`[menu-config] "pinnedMenu" must be an object`);
+    throw new Error(`${errorPrefix} "pinnedMenu" must be an object`);
   }
 
   const menu = raw as Record<string, unknown>;
@@ -109,7 +109,7 @@ function normalizePinnedMenu(raw: unknown): PinnedMenuOption | null {
   const labelRaw = menu.label;
 
   if (typeof sourceDirRaw !== "string" || sourceDirRaw.trim().length === 0) {
-    throw new Error(`[menu-config] "pinnedMenu.sourceDir" must be a non-empty string`);
+    throw new Error(`${errorPrefix} "pinnedMenu.sourceDir" must be a non-empty string`);
   }
 
   const normalizedSourceDir = sourceDirRaw
@@ -118,7 +118,7 @@ function normalizePinnedMenu(raw: unknown): PinnedMenuOption | null {
     .replace(/^\/+/, "")
     .replace(/\/+$/, "");
   if (!normalizedSourceDir) {
-    throw new Error(`[menu-config] "pinnedMenu.sourceDir" must not be root`);
+    throw new Error(`${errorPrefix} "pinnedMenu.sourceDir" must not be root`);
   }
 
   const label =
@@ -157,7 +157,7 @@ export async function loadPinnedMenuConfig(
     throw new Error("[menu-config] top-level JSON must be an object");
   }
 
-  return normalizePinnedMenu((parsed as Record<string, unknown>).pinnedMenu);
+  return normalizePinnedMenu((parsed as Record<string, unknown>).pinnedMenu, "[menu-config]");
 }
 
 export function resolveBuildOptions(
@@ -170,6 +170,8 @@ export function resolveBuildOptions(
   const cliExclude = cli.exclude ?? [];
   const mergedExclude = Array.from(new Set([...DEFAULTS.exclude, ...cfgExclude, ...cliExclude]));
   const seo = normalizeSeoConfig(userConfig.seo);
+  const configPinnedMenu = normalizePinnedMenu(userConfig.pinnedMenu, "[config]");
+  const resolvedPinnedMenu = pinnedMenu ?? configPinnedMenu;
 
   return {
     vaultDir: path.resolve(cwd, cli.vaultDir ?? userConfig.vaultDir ?? DEFAULTS.vaultDir),
@@ -177,7 +179,7 @@ export function resolveBuildOptions(
     exclude: mergedExclude,
     newWithinDays: cli.newWithinDays ?? userConfig.ui?.newWithinDays ?? DEFAULTS.newWithinDays,
     recentLimit: cli.recentLimit ?? userConfig.ui?.recentLimit ?? DEFAULTS.recentLimit,
-    pinnedMenu,
+    pinnedMenu: resolvedPinnedMenu,
     wikilinks: userConfig.markdown?.wikilinks ?? DEFAULTS.wikilinks,
     imagePolicy: userConfig.markdown?.images ?? DEFAULTS.imagePolicy,
     gfm: userConfig.markdown?.gfm ?? DEFAULTS.gfm,
@@ -199,7 +201,7 @@ Options:
   --exclude <glob>          Exclude glob pattern (repeatable)
   --new-within-days <n>     NEW badge threshold days (default: 7)
   --recent-limit <n>        Recent virtual folder item count (default: 5)
-  --menu-config <path>      JSON file path for pinned menu config
+  --menu-config <path>      JSON file path to override pinnedMenu (optional)
   --port <n>                Dev server port (default: 3000)
   -h, --help                Show help
 `);

package/src/markdown.ts

@@ -16,6 +16,13 @@ export interface MarkdownRenderer {
 }
 
 const FENCE_LANG_RE = /^```([\w-+#.]+)/gm;
+type RenderRule = NonNullable<MarkdownIt["renderer"]["rules"]["fence"]>;
+type RenderRuleArgs = Parameters<RenderRule>;
+type RuleTokens = RenderRuleArgs[0];
+type RuleOptions = RenderRuleArgs[2];
+type RuleEnv = RenderRuleArgs[3];
+type RuleSelf = RenderRuleArgs[4];
+type LinkOpenRule = NonNullable<MarkdownIt["renderer"]["rules"]["link_open"]>;
 
 function escapeMarkdownLabel(input: string): string {
   return input.replace(/[\[\]]/g, "");
@@ -87,13 +94,18 @@ function preprocessMarkdown(
   return { markdown: output, warnings };
 }
 
-type Highlighter = HighlighterGeneric<string, string>;
-
-async function loadFenceLanguages(highlighter: Highlighter, loaded: Set<string>, markdown: string): Promise<void> {
+async function loadFenceLanguages<L extends string, T extends string>(
+  highlighter: HighlighterGeneric<L, T>,
+  loaded: Set<string>,
+  markdown: string,
+): Promise<void> {
   const langs = new Set<string>();
   FENCE_LANG_RE.lastIndex = 0;
-  let match: RegExpExecArray | null;
-  while ((match = FENCE_LANG_RE.exec(markdown)) !== null) {
+  while (true) {
+    const match = FENCE_LANG_RE.exec(markdown);
+    if (match === null) {
+      break;
+    }
     if (match[1]) {
       langs.add(match[1].toLowerCase());
     }
@@ -104,7 +116,7 @@ async function loadFenceLanguages(highlighter: Highlighter, loaded: Set<string>,
       continue;
     }
     try {
-      await highlighter.loadLanguage(lang as never);
+      await highlighter.loadLanguage(lang as L);
       loaded.add(lang);
     } catch {
       // Unknown language: fallback to plaintext in fence renderer.
@@ -116,7 +128,11 @@ function escapeHtmlAttr(input: string): string {
   return input.replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 
-function createMarkdownIt(highlighter: Highlighter, theme: string, gfm: boolean): MarkdownIt {
+function createMarkdownIt<L extends string, T extends string>(
+  highlighter: HighlighterGeneric<L, T>,
+  theme: string,
+  gfm: boolean,
+): MarkdownIt {
   const md = new MarkdownIt({
     // Allow raw HTML in markdown (e.g. <img ... />).
     html: true,
@@ -129,7 +145,7 @@ function createMarkdownIt(highlighter: Highlighter, theme: string, gfm: boolean)
     md.disable(["table", "strikethrough"]);
   }
 
-  md.renderer.rules.fence = (tokens: any[], idx: number) => {
+  const fenceRule: RenderRule = (tokens: RuleTokens, idx: number, _options: RuleOptions, _env: RuleEnv, _self: RuleSelf) => {
     const token = tokens[idx];
     const info = token.info.trim();
     const parts = info.split(/\s+/);
@@ -139,12 +155,12 @@ function createMarkdownIt(highlighter: Highlighter, theme: string, gfm: boolean)
     let codeHtml: string;
     try {
       codeHtml = highlighter.codeToHtml(token.content, {
-        lang: lang || "text",
+        lang: (lang || "text") as never,
         theme,
       });
     } catch {
       codeHtml = highlighter.codeToHtml(token.content, {
-        lang: "text",
+        lang: "text" as never,
         theme,
       });
     }
@@ -163,9 +179,16 @@ function createMarkdownIt(highlighter: Highlighter, theme: string, gfm: boolean)
 
     return `<div class="code-block">${header}${codeHtml}</div>`;
   };
-
-  const defaultLinkOpen = md.renderer.rules.link_open;
-  md.renderer.rules.link_open = (tokens: any[], idx: number, options: any, env: any, self: any) => {
+  md.renderer.rules.fence = fenceRule;
+
+  const defaultLinkOpen = md.renderer.rules.link_open as LinkOpenRule | undefined;
+  const linkOpenRule: LinkOpenRule = (
+    tokens: RuleTokens,
+    idx: number,
+    options: RuleOptions,
+    env: RuleEnv,
+    self: RuleSelf,
+  ) => {
     const hrefIdx = tokens[idx].attrIndex("href");
     if (hrefIdx >= 0) {
       const href = tokens[idx].attrs?.[hrefIdx]?.[1] ?? "";
@@ -180,6 +203,7 @@ function createMarkdownIt(highlighter: Highlighter, theme: string, gfm: boolean)
     }
     return self.renderToken(tokens, idx, options);
   };
+  md.renderer.rules.link_open = linkOpenRule;
 
   return md;
 }

package/src/runtime/app.css

@@ -192,6 +192,12 @@ a:hover {
 }
 
 .material-symbols-outlined {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1em;
+  height: 1em;
+  flex: 0 0 auto;
   font-size: 20px;
   line-height: 1;
   vertical-align: middle;
@@ -754,6 +760,7 @@ body.mobile-toggle-left .mobile-menu-toggle {
   overflow-x: auto;
   overflow-y: hidden;
   white-space: nowrap;
+  min-height: 24px;
 }
 
 .breadcrumb-sep {
@@ -793,6 +800,7 @@ body.mobile-toggle-left .mobile-menu-toggle {
 /* Viewer header */
 .viewer-header {
   margin-bottom: 32px;
+  min-height: 88px;
 }
 
 .viewer-title {
@@ -808,6 +816,7 @@ body.mobile-toggle-left .mobile-menu-toggle {
   display: flex;
   align-items: center;
   gap: 16px;
+  min-height: 22px;
   font-size: 0.85rem;
   font-family: "JetBrains Mono", monospace;
   color: var(--latte-subtext0);
@@ -1064,6 +1073,7 @@ body.mobile-toggle-left .mobile-menu-toggle {
 
 /* Images */
 .viewer-content img {
+  display: block;
   max-width: 100%;
   height: auto;
   border-radius: 8px;

package/src/runtime/app.js

@@ -47,6 +47,41 @@ function normalizeRoute(pathname) {
   return route;
 }
 
+function loadInitialViewData() {
+  const script = document.getElementById("initial-view-data");
+  if (!(script instanceof HTMLScriptElement)) {
+    return null;
+  }
+
+  const raw = script.textContent;
+  if (!raw) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") {
+      return null;
+    }
+
+    const route = typeof parsed.route === "string" ? normalizeRoute(parsed.route) : null;
+    const docId = typeof parsed.docId === "string" ? parsed.docId : null;
+    const title = typeof parsed.title === "string" ? parsed.title : null;
+
+    if (!route || !docId || !title) {
+      return null;
+    }
+
+    return {
+      route,
+      docId,
+      title,
+    };
+  } catch {
+    return null;
+  }
+}
+
 function resolveRouteFromLocation(routeMap) {
   const direct = normalizeRoute(location.pathname);
   if (routeMap[direct]) {
@@ -690,6 +725,8 @@ async function start() {
   const navEl = document.getElementById("viewer-nav");
   const a11yStatusEl = document.getElementById("a11y-status");
   const viewerEl = document.querySelector(".viewer");
+  const initialViewData = loadInitialViewData();
+  let hasHydratedInitialView = false;
 
   let hideTreeTooltip = () => {};
   let disposeTreeTooltip = () => {};
@@ -1155,7 +1192,7 @@ async function start() {
 
   const state = {
     expanded,
-    currentDocId: "",
+    currentDocId: initialViewData?.docId ?? "",
     async navigate(rawRoute, push) {
       hideTreeTooltip();
 
@@ -1206,6 +1243,23 @@ async function start() {
 
       state.currentDocId = id;
       markActive(treeFileRowsById, activeFileState, id);
+
+      const shouldUseInitialView =
+        !hasHydratedInitialView &&
+        initialViewData &&
+        initialViewData.docId === id &&
+        initialViewData.route === route;
+
+      if (shouldUseInitialView) {
+        hasHydratedInitialView = true;
+        document.title = `${initialViewData.title} - File-System Blog`;
+        if (viewerEl instanceof HTMLElement) {
+          viewerEl.scrollTo(0, 0);
+        }
+        announceA11yStatus(`탐색 완료: ${doc.title} 문서를 열었습니다.`);
+        return;
+      }
+
       breadcrumbEl.innerHTML = renderBreadcrumb(route);
       titleEl.textContent = doc.title;
       metaEl.innerHTML = renderMeta(doc);

package/src/seo.ts

@@ -57,9 +57,35 @@ export function normalizeSeoConfig(raw: UserSeoConfig | undefined): BuildSeoOpti
     throw new Error('[config] "seo.pathBase" must be a string when provided (for example: "/blog")');
   }
 
+  const normalizeOptionalString = (value: unknown, key: string): string | undefined => {
+    if (value == null) {
+      return undefined;
+    }
+    if (typeof value !== "string") {
+      throw new Error(`[config] "seo.${key}" must be a string when provided`);
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+  };
+
+  const twitterCardRaw = raw.twitterCard;
+  if (twitterCardRaw != null && twitterCardRaw !== "summary" && twitterCardRaw !== "summary_large_image") {
+    throw new Error('[config] "seo.twitterCard" must be "summary" or "summary_large_image" when provided');
+  }
+
   return {
     siteUrl: parsed.origin,
     pathBase: normalizePathBase(pathBaseRaw ?? ""),
+    siteName: normalizeOptionalString(raw.siteName, "siteName"),
+    defaultTitle: normalizeOptionalString(raw.defaultTitle, "defaultTitle"),
+    defaultDescription: normalizeOptionalString(raw.defaultDescription, "defaultDescription"),
+    locale: normalizeOptionalString(raw.locale, "locale"),
+    twitterCard: twitterCardRaw,
+    twitterSite: normalizeOptionalString(raw.twitterSite, "twitterSite"),
+    twitterCreator: normalizeOptionalString(raw.twitterCreator, "twitterCreator"),
+    defaultSocialImage: normalizeOptionalString(raw.defaultSocialImage, "defaultSocialImage"),
+    defaultOgImage: normalizeOptionalString(raw.defaultOgImage, "defaultOgImage"),
+    defaultTwitterImage: normalizeOptionalString(raw.defaultTwitterImage, "defaultTwitterImage"),
   };
 }
 

package/src/template.ts

@@ -9,6 +9,8 @@ export interface AppShellMeta {
   canonicalUrl?: string;
   ogTitle?: string;
   ogType?: string;
+  ogSiteName?: string;
+  ogLocale?: string;
   ogUrl?: string;
   ogDescription?: string;
   ogImage?: string;
@@ -16,9 +18,37 @@ export interface AppShellMeta {
   twitterTitle?: string;
   twitterDescription?: string;
   twitterImage?: string;
+  twitterSite?: string;
+  twitterCreator?: string;
   jsonLd?: unknown | unknown[];
 }
 
+export interface AppShellAssets {
+  cssHref: string;
+  jsSrc: string;
+}
+
+export interface AppShellInitialView {
+  route: string;
+  docId: string;
+  title: string;
+  breadcrumbHtml: string;
+  metaHtml: string;
+  contentHtml: string;
+  navHtml: string;
+}
+
+interface AppShellInitialViewPayload {
+  route: string;
+  docId: string;
+  title: string;
+}
+
+const DEFAULT_ASSETS: AppShellAssets = {
+  cssHref: "/assets/app.css",
+  jsSrc: "/assets/app.js",
+};
+
 function normalizeJsonLd(value: unknown | unknown[] | undefined): unknown[] {
   if (Array.isArray(value)) {
     return value.filter((item) => item != null);
@@ -36,10 +66,13 @@ function stringifyJsonLd(value: unknown): string {
 function renderHeadMeta(meta: AppShellMeta): string {
   const title = (meta.title ?? DEFAULT_TITLE).trim() || DEFAULT_TITLE;
   const description = typeof meta.description === "string" ? meta.description.trim() : "";
+  const fallbackDescription = description || DEFAULT_DESCRIPTION;
   const canonicalUrl = typeof meta.canonicalUrl === "string" ? meta.canonicalUrl.trim() : "";
 
   const ogTitle = (meta.ogTitle ?? title).trim() || title;
   const ogType = (meta.ogType ?? "website").trim() || "website";
+  const ogSiteName = typeof meta.ogSiteName === "string" ? meta.ogSiteName.trim() : "";
+  const ogLocale = typeof meta.ogLocale === "string" ? meta.ogLocale.trim() : "";
   const ogUrl = typeof meta.ogUrl === "string" ? meta.ogUrl.trim() : "";
   const ogDescription = (meta.ogDescription ?? (description || DEFAULT_DESCRIPTION)).trim() || DEFAULT_DESCRIPTION;
   const ogImage = typeof meta.ogImage === "string" ? meta.ogImage.trim() : "";
@@ -48,13 +81,13 @@ function renderHeadMeta(meta: AppShellMeta): string {
   const twitterTitle = (meta.twitterTitle ?? title).trim() || title;
   const twitterDescription = (meta.twitterDescription ?? (description || DEFAULT_DESCRIPTION)).trim() || DEFAULT_DESCRIPTION;
   const twitterImage = typeof meta.twitterImage === "string" ? meta.twitterImage.trim() : "";
+  const twitterSite = typeof meta.twitterSite === "string" ? meta.twitterSite.trim() : "";
+  const twitterCreator = typeof meta.twitterCreator === "string" ? meta.twitterCreator.trim() : "";
   const jsonLd = normalizeJsonLd(meta.jsonLd);
 
   const headTags: string[] = [`    <title>${escapeHtmlAttribute(title)}</title>`];
 
-  if (description) {
-    headTags.push(`    <meta name="description" content="${escapeHtmlAttribute(description)}" />`);
-  }
+  headTags.push(`    <meta name="description" content="${escapeHtmlAttribute(fallbackDescription)}" />`);
 
   if (canonicalUrl) {
     headTags.push(`    <link rel="canonical" href="${escapeHtmlAttribute(canonicalUrl)}" />`);
@@ -67,6 +100,14 @@ function renderHeadMeta(meta: AppShellMeta): string {
     headTags.push(`    <meta property="og:url" content="${escapeHtmlAttribute(ogUrl)}" />`);
   }
 
+  if (ogSiteName) {
+    headTags.push(`    <meta property="og:site_name" content="${escapeHtmlAttribute(ogSiteName)}" />`);
+  }
+
+  if (ogLocale) {
+    headTags.push(`    <meta property="og:locale" content="${escapeHtmlAttribute(ogLocale)}" />`);
+  }
+
   headTags.push(`    <meta property="og:description" content="${escapeHtmlAttribute(ogDescription)}" />`);
 
   if (ogImage) {
@@ -81,6 +122,14 @@ function renderHeadMeta(meta: AppShellMeta): string {
     headTags.push(`    <meta name="twitter:image" content="${escapeHtmlAttribute(twitterImage)}" />`);
   }
 
+  if (twitterSite) {
+    headTags.push(`    <meta name="twitter:site" content="${escapeHtmlAttribute(twitterSite)}" />`);
+  }
+
+  if (twitterCreator) {
+    headTags.push(`    <meta name="twitter:creator" content="${escapeHtmlAttribute(twitterCreator)}" />`);
+  }
+
   for (const schema of jsonLd) {
     headTags.push(`    <script type="application/ld+json">${stringifyJsonLd(schema)}</script>`);
   }
@@ -88,8 +137,51 @@ function renderHeadMeta(meta: AppShellMeta): string {
   return headTags.join("\n");
 }
 
-export function renderAppShellHtml(meta: AppShellMeta = {}): string {
+function renderDeferredStylesheet(href: string): string {
+  return [
+    `    <link rel="preload" href="${escapeHtmlAttribute(href)}" as="style" />`,
+    `    <link rel="stylesheet" href="${escapeHtmlAttribute(href)}" media="print" onload="this.media='all'" />`,
+    `    <noscript><link rel="stylesheet" href="${escapeHtmlAttribute(href)}" /></noscript>`,
+  ].join("\n");
+}
+
+function renderInitialViewScript(initialView: AppShellInitialView | null): string {
+  if (!initialView) {
+    return "";
+  }
+
+  const payloadData: AppShellInitialViewPayload = {
+    route: initialView.route,
+    docId: initialView.docId,
+    title: initialView.title,
+  };
+
+  const payload = JSON.stringify(payloadData)
+    .replaceAll("<", "\\u003c")
+    .replaceAll("\u2028", "\\u2028")
+    .replaceAll("\u2029", "\\u2029");
+
+  return `\n    <script id="initial-view-data" type="application/json">${payload}</script>`;
+}
+
+export function renderAppShellHtml(
+  meta: AppShellMeta = {},
+  assets: AppShellAssets = DEFAULT_ASSETS,
+  initialView: AppShellInitialView | null = null,
+): string {
   const headMeta = renderHeadMeta(meta);
+  const initialViewScript = renderInitialViewScript(initialView);
+  const textFontStylesheet =
+    "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&family=Noto+Sans+KR:wght@400;500;700&display=optional";
+  const symbolFontStylesheet =
+    "https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:wght,FILL@100..700,0..1&display=optional";
+  const initialTitle = initialView ? escapeHtmlAttribute(initialView.title) : "문서를 선택하세요";
+  const initialBreadcrumb = initialView ? initialView.breadcrumbHtml : "";
+  const initialMeta = initialView ? initialView.metaHtml : "";
+  const initialContent = initialView
+    ? initialView.contentHtml
+    : '<p class="placeholder">좌측 탐색기에서 문서를 선택하세요.</p>';
+  const initialNav = initialView ? initialView.navHtml : "";
 
   return `<!doctype html>
 <html lang="ko">
@@ -99,9 +191,9 @@ export function renderAppShellHtml(meta: AppShellMeta = {}): string {
 ${headMeta}
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&family=Noto+Sans+KR:wght@400;500;700&display=swap" rel="stylesheet" />
-    <link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:wght,FILL@100..700,0..1&display=swap" rel="stylesheet" />
-    <link rel="stylesheet" href="/assets/app.css" />
+${renderDeferredStylesheet(textFontStylesheet)}
+${renderDeferredStylesheet(symbolFontStylesheet)}
+    <link rel="stylesheet" href="${escapeHtmlAttribute(assets.cssHref)}" />
   </head>
   <body>
     <a class="skip-link" href="#viewer-panel">본문으로 건너뛰기</a>
@@ -200,26 +292,30 @@ ${headMeta}
           <span>Files</span>
         </button>
         <div class="viewer-container">
-          <nav id="viewer-breadcrumb" class="viewer-breadcrumb" aria-label="경로"></nav>
+          <nav id="viewer-breadcrumb" class="viewer-breadcrumb" aria-label="경로">${initialBreadcrumb}</nav>
           <header id="viewer-header" class="viewer-header">
-            <h1 id="viewer-title" class="viewer-title">문서를 선택하세요</h1>
-            <div id="viewer-meta" class="viewer-meta"></div>
+            <h1 id="viewer-title" class="viewer-title">${initialTitle}</h1>
+            <div id="viewer-meta" class="viewer-meta">${initialMeta}</div>
           </header>
-          <article id="viewer-content" class="viewer-content">
-            <p class="placeholder">좌측 탐색기에서 문서를 선택하세요.</p>
-          </article>
-          <nav id="viewer-nav" class="viewer-nav"></nav>
+          <article id="viewer-content" class="viewer-content">${initialContent}</article>
+          <nav id="viewer-nav" class="viewer-nav">${initialNav}</nav>
         </div>
       </main>
     </div>
     <div id="tree-label-tooltip" class="tree-label-tooltip" role="tooltip" hidden></div>
-    <script type="module" src="/assets/app.js"></script>
+${initialViewScript}
+    <script type="module" src="${escapeHtmlAttribute(assets.jsSrc)}"></script>
   </body>
 </html>
 `;
 }
 
-export function render404Html(): string {
+export function render404Html(assets: AppShellAssets = DEFAULT_ASSETS): string {
+  const textFontStylesheet =
+    "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&family=Noto+Sans+KR:wght@400;500;700&display=optional";
+  const symbolFontStylesheet =
+    "https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:wght,FILL@100..700,0..1&display=optional";
+
   return `<!doctype html>
 <html lang="ko">
   <head>
@@ -228,9 +324,9 @@ export function render404Html(): string {
     <title>404 - File-System Blog</title>
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&family=Noto+Sans+KR:wght@400;500;700&display=swap" rel="stylesheet" />
-    <link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:wght,FILL@100..700,0..1&display=swap" rel="stylesheet" />
-    <link rel="stylesheet" href="/assets/app.css" />
+${renderDeferredStylesheet(textFontStylesheet)}
+${renderDeferredStylesheet(symbolFontStylesheet)}
+    <link rel="stylesheet" href="${escapeHtmlAttribute(assets.cssHref)}" />
   </head>
   <body>
     <main class="not-found">

package/src/types.ts

@@ -3,11 +3,31 @@ export type ImagePolicy = "keep" | "omit-local";
 export interface UserSeoConfig {
   siteUrl?: string;
   pathBase?: string;
+  siteName?: string;
+  defaultTitle?: string;
+  defaultDescription?: string;
+  locale?: string;
+  twitterCard?: "summary" | "summary_large_image";
+  twitterSite?: string;
+  twitterCreator?: string;
+  defaultSocialImage?: string;
+  defaultOgImage?: string;
+  defaultTwitterImage?: string;
 }
 
 export interface BuildSeoOptions {
   siteUrl: string;
   pathBase: string;
+  siteName?: string;
+  defaultTitle?: string;
+  defaultDescription?: string;
+  locale?: string;
+  twitterCard?: "summary" | "summary_large_image";
+  twitterSite?: string;
+  twitterCreator?: string;
+  defaultSocialImage?: string;
+  defaultOgImage?: string;
+  defaultTwitterImage?: string;
 }
 
 export interface PinnedMenuOption {
@@ -19,6 +39,10 @@ export interface UserConfig {
   vaultDir?: string;
   outDir?: string;
   exclude?: string[];
+  pinnedMenu?: {
+    label?: string;
+    sourceDir: string;
+  };
   ui?: {
     newWithinDays?: number;
     recentLimit?: number;