@limcpf/everything-is-a-markdown 0.6.7 → 0.6.8

package/README.ko.md

@@ -3,11 +3,13 @@
 언어: [English](README.md) | **한국어**
 
 Everything-Is-A-Markdown은 로컬 Markdown 볼트를 정적 웹사이트로 빌드해, 폴더/파일 탐색 구조를 유지한 채 공개할 수 있게 해주는 CLI 도구입니다.
+공개 URL은 `prefix` 기준으로 생성되고, 사이드바 폴더 구조는 실제 파일 경로가 아니라 `category_path` 기준으로 만들어집니다.
 
 ## 이 앱은 무엇을 하나요
 
 - Markdown 볼트에서 정적 문서/블로그 사이트를 생성
 - `publish: true` 문서만 선택적으로 공개
+- 공개 문서는 `prefix`와 `category_path`를 필수로 사용
 - 비공개 노트와 공개 콘텐츠 분리
 
 ## Obsidian 사용자에게 특히 잘 맞습니다
@@ -73,6 +75,10 @@ const config = {
   vaultDir: "./vault",
   outDir: "./dist",
   staticPaths: ["assets", "public/favicon.ico"],
+  pinnedMenu: {
+    label: "NOTICE",
+    categoryPath: "announcements",
+  },
   seo: {
     siteUrl: "https://example.com",
     pathBase: "/blog",
@@ -97,6 +103,12 @@ export default config;
 - 지정한 경로의 파일들을 `dist`에 같은 상대 경로로 복사
 - 예: 볼트 `assets/og.png` -> `dist/assets/og.png`
 
+`pinnedMenu`:
+
+- `categoryPath`: 문서 frontmatter `category_path` prefix 기준으로 가상 폴더를 구성
+- `sourceDir`: 기존 파일 경로 prefix 기준
+- 둘 다 있으면 `categoryPath`가 우선
+
 `seo.pathBase`:
 
 - 서브패스 배포(예: `/blog`)를 정식 지원합니다.
@@ -123,7 +135,9 @@ bun run build -- --vault ./test-vault --out ./dist
   이 값이 `true`인 문서만 빌드 결과에 포함됩니다.
 - `prefix: "A-01"`  
   문서의 공개 식별자이자 라우트(`/A-01/`) 기준입니다.  
-  `publish: true`인데 `prefix`가 없으면 빌드 경고를 출력하고 문서를 제외합니다.
+- `category_path: "engineering/blog/frontend"`  
+  사이드바 폴더 구조 기준입니다.
+  `publish: true`인데 `prefix`나 `category_path`가 없으면 빌드 경고를 출력하고 문서를 제외합니다.
 
 선택:
 
@@ -150,6 +164,7 @@ bun run build -- --vault ./test-vault --out ./dist
 ---
 publish: true
 prefix: "DEV-01"
+category_path: "guides/setup"
 branch: dev
 title: Setup Guide
 date: "2024-09-15"

package/README.md

@@ -13,7 +13,8 @@ The generated site keeps a two-panel experience:
 
 - Builds a static site from a local Markdown vault
 - Publishes only notes with `publish: true`
-- Requires a `prefix` field for every published note and uses it as the public route
+- Requires `prefix` and `category_path` for every published note
+- Uses `prefix` as the public route and `category_path` as the sidebar folder path
 - Supports Obsidian-style wikilinks such as `[[note]]` and `[[note|label]]`
 - Renders code blocks with Shiki
 - Renders Mermaid blocks in the browser with runtime fallback handling
@@ -25,7 +26,7 @@ The generated site keeps a two-panel experience:
 
 ## Important Behavior
 
-This project currently uses `prefix`-based public routes, not vault-relative path routes.
+This project currently uses `prefix`-based public routes, not vault-relative path routes. Sidebar folders are built from `category_path`, not from the actual file location.
 
 Example:
 
@@ -125,8 +126,9 @@ Only documents with `publish: true` are considered for output.
 
 - `publish: true`
 - `prefix: "BC-VO-02"`
+- `category_path: "engineering/blog/frontend"`
 
-If `publish: true` is set but `prefix` is missing, the note is skipped and a build warning is emitted.
+If `publish: true` is set but `prefix` or `category_path` is missing, the note is skipped and a build warning is emitted.
 
 ### Supported fields
 
@@ -144,6 +146,7 @@ Example:
 ---
 publish: true
 prefix: BC-VO-02
+category_path: engineering/blog/frontend
 branch: dev
 title: Setup Guide
 date: "2024-09-15"
@@ -157,6 +160,8 @@ tags: ["tutorial", "setup"]
 
 Public routes are derived from `prefix`, not from the file path.
 
+Sidebar folders are derived from `category_path`, not from the file path.
+
 Normalization rules:
 
 - trims whitespace
@@ -225,7 +230,7 @@ export default {
   staticPaths: ["assets", "public/favicon.ico"],
   pinnedMenu: {
     label: "NOTICE",
-    sourceDir: "announcements",
+    categoryPath: "announcements",
   },
   ui: {
     newWithinDays: 7,
@@ -269,6 +274,8 @@ export default {
 - `exclude`: extra exclude globs.
 - `staticPaths`: vault-relative files or directories copied into output.
 - `pinnedMenu`: optional virtual folder shown above `Recent`.
+- `pinnedMenu.sourceDir`: optional legacy file-path prefix matcher.
+- `pinnedMenu.categoryPath`: optional category-path prefix matcher for the sidebar virtual folder.
 - `ui.newWithinDays`: threshold for NEW badge.
 - `ui.recentLimit`: number of items in `Recent`.
 - `markdown.wikilinks`: enable or disable wikilink resolution.
@@ -287,14 +294,19 @@ export default {
 
 ### `pinnedMenu`
 
-`pinnedMenu` creates a virtual folder at the top of the sidebar by collecting published docs whose vault-relative path starts with the configured `sourceDir`.
+`pinnedMenu` creates a virtual folder at the top of the sidebar by collecting published docs that match either:
+
+- `categoryPath`: the document `category_path` equals or starts with the configured prefix
+- `sourceDir`: the vault-relative file path starts with the configured prefix
+
+If both are present, `categoryPath` wins.
 
 Example:
 
 ```ts
 pinnedMenu: {
   label: "NOTICE",
-  sourceDir: "announcements",
+  categoryPath: "announcements",
 }
 ```
 
@@ -310,7 +322,7 @@ JSON shape:
 {
   "pinnedMenu": {
     "label": "NOTICE",
-    "sourceDir": "announcements"
+    "categoryPath": "announcements"
   }
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@limcpf/everything-is-a-markdown",
-	"version": "0.6.7",
+	"version": "0.6.8",
 	"license": "MIT",
 	"private": false,
 	"type": "module",

package/src/build.ts

@@ -21,7 +21,7 @@ import {
   toDocId,
 } from "./utils";
 
-const CACHE_VERSION = 3;
+const CACHE_VERSION = 4;
 const CACHE_DIR_NAME = ".cache";
 const CACHE_FILE_NAME = "build-index.json";
 const DEFAULT_BRANCH = "dev";
@@ -125,6 +125,7 @@ function normalizeCachedSourceEntry(value: unknown): CachedSourceEntry | null {
   const draft = value.draft === true;
   const title = typeof value.title === "string" && value.title.trim().length > 0 ? value.title.trim() : undefined;
   const prefix = typeof value.prefix === "string" && value.prefix.trim().length > 0 ? value.prefix.trim() : undefined;
+  const categoryPath = normalizeCategoryPath(value.categoryPath);
   const date = typeof value.date === "string" && value.date.trim().length > 0 ? value.date.trim() : undefined;
   const updatedDate =
     typeof value.updatedDate === "string" && value.updatedDate.trim().length > 0 ? value.updatedDate.trim() : undefined;
@@ -147,6 +148,7 @@ function normalizeCachedSourceEntry(value: unknown): CachedSourceEntry | null {
     draft,
     title,
     prefix,
+    categoryPath,
     date,
     updatedDate,
     description,
@@ -276,6 +278,24 @@ function normalizeFrontmatterDate(value: unknown): string | null {
   return null;
 }
 
+function normalizeCategoryPath(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+
+  const normalized = value
+    .trim()
+    .replace(/\\/g, "/")
+    .replace(/^\/+/, "")
+    .replace(/\/+$/, "")
+    .split("/")
+    .map((segment) => segment.trim())
+    .filter(Boolean)
+    .join("/");
+
+  return normalized.length > 0 ? normalized : undefined;
+}
+
 function extractFrontmatterScalar(raw: string, key: string): string | null {
   const frontmatterMatch = raw.match(/^---\s*\r?\n([\s\S]*?)\r?\n---/);
   if (!frontmatterMatch) {
@@ -353,6 +373,15 @@ function pickDocPrefix(frontmatter: Record<string, unknown>, raw: string): strin
   return undefined;
 }
 
+function pickDocCategoryPath(frontmatter: Record<string, unknown>, raw: string): string | undefined {
+  const literal = normalizeCategoryPath(extractFrontmatterScalar(raw, "category_path"));
+  if (literal) {
+    return literal;
+  }
+
+  return normalizeCategoryPath(frontmatter.category_path);
+}
+
 function appendRouteSuffix(route: string, suffix: string): string {
   const clean = route.replace(/^\/+/, "").replace(/\/+$/, "");
   if (!clean) {
@@ -470,6 +499,7 @@ function toCachedSourceEntry(raw: string, parsed: matter.GrayMatterFile<string>)
     draft: parsed.data.draft === true,
     title: typeof parsed.data.title === "string" && parsed.data.title.trim().length > 0 ? parsed.data.title.trim() : undefined,
     prefix: pickDocPrefix(parsed.data as Record<string, unknown>, raw),
+    categoryPath: pickDocCategoryPath(parsed.data as Record<string, unknown>, raw),
     date: pickDocDate(parsed.data as Record<string, unknown>, raw),
     updatedDate: pickDocUpdatedDate(parsed.data as Record<string, unknown>, raw),
     description: typeof parsed.data.description === "string" ? parsed.data.description.trim() || undefined : undefined,
@@ -500,6 +530,7 @@ function toDocRecord(
     fileName,
     title: entry.title ?? makeTitleFromFileName(fileName),
     prefix: entry.prefix,
+    categoryPath: entry.categoryPath ?? "",
     date: entry.date,
     updatedDate: entry.updatedDate,
     description: entry.description,
@@ -564,6 +595,12 @@ async function readPublishedDocs(options: BuildOptions, previousSources: BuildCa
       console.warn(`[publish] Skipped published doc without prefix: ${relPath}`);
       continue;
     }
+
+    if (!completeEntry.categoryPath) {
+      console.warn(`[publish] Skipped published doc without category_path: ${relPath}`);
+      continue;
+    }
+
     docs.push(toDocRecord(sourcePath, relPath, completeEntry, newThreshold));
   }
 
@@ -755,6 +792,10 @@ function compareByRecentDateThenPath(left: DocRecord, right: DocRecord): number
   return left.relNoExt.localeCompare(right.relNoExt, "ko-KR");
 }
 
+function matchesPathPrefix(value: string, prefix: string): boolean {
+  return value === prefix || value.startsWith(`${prefix}/`);
+}
+
 function pickHomeDoc(docs: DocRecord[]): DocRecord | null {
   const inDefaultBranch = docs.filter((doc) => doc.branch == null || doc.branch === DEFAULT_BRANCH);
   const candidates = inDefaultBranch.length > 0 ? inDefaultBranch : docs;
@@ -771,17 +812,27 @@ function buildPinnedMenuFolder(docs: DocRecord[], options: BuildOptions): Folder
     return null;
   }
 
+  const categoryPath = options.pinnedMenu.categoryPath;
   const sourceDir = options.pinnedMenu.sourceDir;
-  const sourcePrefix = `${sourceDir}/`;
   const children = docs
-    .filter((doc) => doc.relNoExt.startsWith(sourcePrefix))
+    .filter((doc) => {
+      if (categoryPath) {
+        return matchesPathPrefix(doc.categoryPath, categoryPath);
+      }
+      if (sourceDir) {
+        return matchesPathPrefix(doc.relNoExt, sourceDir);
+      }
+      return false;
+    })
     .sort((left, right) => left.relNoExt.localeCompare(right.relNoExt, "ko-KR"))
     .map((doc) => fileNodeFromDoc(doc));
 
+  const pathKey = categoryPath ? `category/${categoryPath}` : `source/${sourceDir ?? "unknown"}`;
+
   return {
     type: "folder",
     name: options.pinnedMenu.label,
-    path: `__virtual__/pinned/${sourceDir}`,
+    path: `__virtual__/pinned/${pathKey}`,
     virtual: true,
     children,
   };
@@ -799,8 +850,7 @@ function buildTree(docs: DocRecord[], options: BuildOptions): TreeNode[] {
   folderIndex.set("", root);
 
   for (const doc of docs) {
-    const segments = doc.relNoExt.split("/");
-    const folders = segments.slice(0, -1);
+    const folders = doc.categoryPath.split("/");
 
     let currentPath = "";
     let parent = root;
@@ -861,6 +911,7 @@ function buildManifest(docs: DocRecord[], tree: TreeNode[], options: BuildOption
     route: doc.route,
     title: doc.title,
     prefix: doc.prefix,
+    categoryPath: doc.categoryPath,
     date: doc.date,
     updatedDate: doc.updatedDate,
     tags: doc.tags,

package/src/config.ts

@@ -151,19 +151,38 @@ function normalizePinnedMenu(raw: unknown, errorPrefix = "[config]"): PinnedMenu
 
   const menu = raw as Record<string, unknown>;
   const sourceDirRaw = menu.sourceDir;
+  const categoryPathRaw = menu.categoryPath;
   const labelRaw = menu.label;
+  const normalizeMenuPath = (value: unknown, fieldName: "sourceDir" | "categoryPath"): string | undefined => {
+    if (value == null) {
+      return undefined;
+    }
+    if (typeof value !== "string" || value.trim().length === 0) {
+      throw new Error(`${errorPrefix} "pinnedMenu.${fieldName}" must be a non-empty string`);
+    }
 
-  if (typeof sourceDirRaw !== "string" || sourceDirRaw.trim().length === 0) {
-    throw new Error(`${errorPrefix} "pinnedMenu.sourceDir" must be a non-empty string`);
-  }
+    const normalized = value
+      .trim()
+      .replace(/\\/g, "/")
+      .replace(/^\/+/, "")
+      .replace(/\/+$/, "")
+      .split("/")
+      .map((segment) => segment.trim())
+      .filter(Boolean)
+      .join("/");
+
+    if (!normalized) {
+      throw new Error(`${errorPrefix} "pinnedMenu.${fieldName}" must not be root`);
+    }
+
+    return normalized;
+  };
+
+  const normalizedSourceDir = normalizeMenuPath(sourceDirRaw, "sourceDir");
+  const normalizedCategoryPath = normalizeMenuPath(categoryPathRaw, "categoryPath");
 
-  const normalizedSourceDir = sourceDirRaw
-    .trim()
-    .replace(/\\/g, "/")
-    .replace(/^\/+/, "")
-    .replace(/\/+$/, "");
-  if (!normalizedSourceDir) {
-    throw new Error(`${errorPrefix} "pinnedMenu.sourceDir" must not be root`);
+  if (!normalizedSourceDir && !normalizedCategoryPath) {
+    throw new Error(`${errorPrefix} "pinnedMenu" must include "sourceDir" or "categoryPath"`);
   }
 
   const label =
@@ -174,6 +193,7 @@ function normalizePinnedMenu(raw: unknown, errorPrefix = "[config]"): PinnedMenu
   return {
     label,
     sourceDir: normalizedSourceDir,
+    categoryPath: normalizedCategoryPath,
   };
 }
 

package/src/types.ts

@@ -32,7 +32,8 @@ export interface BuildSeoOptions {
 
 export interface PinnedMenuOption {
   label: string;
-  sourceDir: string;
+  sourceDir?: string;
+  categoryPath?: string;
 }
 
 export interface UserConfig {
@@ -42,7 +43,8 @@ export interface UserConfig {
   staticPaths?: string[];
   pinnedMenu?: {
     label?: string;
-    sourceDir: string;
+    sourceDir?: string;
+    categoryPath?: string;
   };
   ui?: {
     newWithinDays?: number;
@@ -96,6 +98,7 @@ export interface DocRecord {
   fileName: string;
   title: string;
   prefix?: string;
+  categoryPath: string;
   date?: string;
   updatedDate?: string;
   description?: string;
@@ -156,6 +159,7 @@ export interface Manifest {
     route: string;
     title: string;
     prefix?: string;
+    categoryPath: string;
     contentUrl: string;
     date?: string;
     updatedDate?: string;
@@ -185,6 +189,7 @@ export interface BuildCache {
       draft: boolean;
       title?: string;
       prefix?: string;
+      categoryPath?: string;
       date?: string;
       updatedDate?: string;
       description?: string;