@limcpf/everything-is-a-markdown 0.4.1 → 0.4.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,128 @@
+# Everything-Is-A-Markdown (EIAM)
+
+언어: [English](README.md) | **한국어**
+
+Everything-Is-A-Markdown은 로컬 Markdown 볼트를 정적 웹사이트로 빌드해, 폴더/파일 탐색 구조를 유지한 채 공개할 수 있게 해주는 CLI 도구입니다.
+
+## 이 앱은 무엇을 하나요
+
+- Markdown 볼트에서 정적 문서/블로그 사이트를 생성
+- `publish: true` 문서만 선택적으로 공개
+- 비공개 노트와 공개 콘텐츠 분리
+
+## Obsidian 사용자에게 특히 잘 맞습니다
+
+- Obsidian에서 평소처럼 작성한 뒤, 공개할 문서만 빌드할 수 있습니다.
+- Obsidian 스타일 위키링크(`[[...]]`)를 지원합니다.
+
+## 설치
+
+```bash
+bun install
+```
+
+## 사용 방법
+
+```bash
+bun run blog [build|dev|clean] [options]
+```
+
+명령:
+
+- `bun run build`: 정적 파일 빌드
+- `bun run dev`: 로컬 개발 서버 실행 (기본 `http://localhost:3000`)
+- `bun run clean`: `dist`와 `.cache` 삭제
+
+자주 쓰는 옵션:
+
+- `--vault <path>`: Markdown 루트 디렉터리 (기본 `.`)
+- `--out <path>`: 출력 디렉터리 (기본 `dist`)
+- `--exclude <glob>`: 제외 패턴 추가 (반복 가능)
+- `--port <n>`: 개발 서버 포트 (기본 `3000`)
+
+예시:
+
+```bash
+# 샘플 볼트로 실행
+bun run dev -- --vault ./test-vault --out ./dist
+
+# 빌드
+bun run build -- --vault ./test-vault --out ./dist
+```
+
+## Markdown Frontmatter
+
+공개 여부를 결정하는 핵심 필드는 `publish`입니다.
+
+필수:
+
+- `publish: true`  
+  이 값이 `true`인 문서만 빌드 결과에 포함됩니다.
+
+선택:
+
+- `draft: true`  
+  `publish: true`여도 문서를 제외합니다.
+- `title: "..."`  
+  문서 제목. 없으면 파일명을 사용합니다.
+- `prefix: "A-01"`  
+  탐색기 제목 앞과 본문 메타 줄에 표시할 짧은 코드.
+- `branch: dev`  
+  브랜치 필터 분류값.
+- `description: "..."`  
+  요약 설명.
+- `tags: ["tag1", "tag2"]`  
+  문자열 배열.
+- `date: "YYYY-MM-DD"` 또는 `createdDate: "..."`  
+  생성일.
+- `updatedDate: "..."` 또는 `modifiedDate: "..."` 또는 `lastModified: "..."`  
+  수정일.
+
+## Frontmatter 예시
+
+게시 문서:
+
+```md
+---
+publish: true
+prefix: "DEV-01"
+branch: dev
+title: Setup Guide
+date: "2024-09-15"
+updatedDate: "2024-09-20T09:30:00"
+description: How to set up your development environment
+tags: ["tutorial", "setup"]
+---
+
+# Setup Guide
+```
+
+비공개 문서 (제외됨):
+
+```md
+---
+publish: false
+title: Internal Notes
+---
+```
+
+초안 문서:
+
+```md
+---
+publish: true
+draft: true
+title: Work In Progress
+---
+```
+
+## bunx 실행 (선택)
+
+```bash
+bunx @limcpf/everything-is-a-markdown build --vault ./vault --out ./dist
+bunx @limcpf/everything-is-a-markdown dev --port 3000
+```
+
+## 라이선스
+
+MIT. `LICENSE` 파일을 참고하세요.

package/README.md

@@ -1,297 +1,128 @@
 # Everything-Is-A-Markdown (EIAM)
 
-로컬 Markdown 볼트를 **파일 탐색기 UX 그대로** 웹에 공개할 수 있게 만드는 정적 블로그 빌더입니다.
-
-- 문서 저장 구조(폴더/파일)를 그대로 살려서 탐색 경험을 제공합니다.
-- `publish: true` 문서만 빌드해, 로컬 지식베이스와 공개 콘텐츠를 분리할 수 있습니다.
-- 결과물은 순수 HTML/CSS/JS 정적 파일이라 배포가 단순합니다.
-
-**왜 이 프로젝트인가**
-- 파일 트리 + 브랜치 필터 + 본문 뷰를 하나의 화면에 결합해 "문서 저장소를 읽는 경험"을 만듭니다.
-- 빌드 캐시(`.cache/build-index.json`)로 변경된 문서만 다시 렌더링해 반복 빌드가 빠릅니다.
-- Obsidian 스타일 위키링크(`[[...]]`)를 지원해 기존 작성 습관을 크게 바꾸지 않아도 됩니다.
-- 문서별 슬러그 고정 URL(`/path/to/doc/`)과 라우트 매핑(`manifest.json`)으로 정적 호스팅에 최적화되어 있습니다.
-- 반응형 사이드바, 설정 팝업, 라이트/시스템/다크 테마 전환까지 기본 제공해 바로 운영 가능한 UI를 제공합니다.
-
-**스크린샷 가이드 (원하는 이미지를 아래 설명으로 캡처해서 넣어주세요)**
-- (대표 화면: 좌측 파일 트리, 우측 본문, 상단 브랜치 필터 pill이 함께 보이는 데스크톱 전체 화면)
-- (브랜치 전환 화면: branch pill 선택 전/후로 목록이 바뀌는 상태)
-- (설정 팝업 화면: 메뉴 버튼 위치 토글 + Light/System/Dark 테마 세그먼트가 보이는 화면)
-- (다크 모드 화면: 동일 문서를 라이트/다크로 비교 가능한 화면)
-- (모바일 화면: 하단 Files 버튼으로 사이드바를 열었을 때 오버레이 포함 화면)
-
-**프로젝트 개요**
-이 프로젝트는 로컬 Markdown 문서를 파일 트리 형태로 탐색하고, 정적 사이트로 빌드하는 File-System 스타일 블로그 생성기입니다.
-
-**주요 기능**
-- 파일 트리 기반 탐색 UI (폴더/파일 구조 유지)
-- 문서별 슬러그 고정 URL 경로 생성 (`/path/to/doc/`)
-- Shiki 기반 코드 하이라이팅
-- Obsidian 스타일 위키링크 `[[...]]` 지원
-- 라이트/시스템/다크 테마 전환 지원 (설정 팝업)
-- NEW 배지, Recent 가상 폴더, 문서 메타 표시
-- 증분 빌드 캐시(`.cache/build-index.json`)로 재빌드 최적화
-
-**빠른 시작**
-1. 의존성 설치
+Language: **English** | [한국어](README.ko.md)
+
+Everything-Is-A-Markdown is a CLI tool that turns a local Markdown vault into a static website while keeping the folder/file navigation experience.
+
+## What This App Is For
+
+- Build a static docs/blog site from your Markdown vault
+- Publish only documents with `publish: true`
+- Keep private notes and public content separate
+
+## Works Great with Obsidian
+
+- You can keep writing in Obsidian and publish selected notes.
+- Obsidian-style wikilinks (`[[...]]`) are supported.
+
+## Install
 
 ```bash
 bun install
 ```
 
-2. 샘플 볼트로 실행
+## Usage
 
 ```bash
-bun run dev -- --vault ./test-vault --out ./dist
+bun run blog [build|dev|clean] [options]
 ```
 
-브라우저에서 `http://localhost:3000`으로 접속합니다.
+Commands:
 
-**사용 방법**
-스크립트는 `bun run`으로 실행합니다.
+- `bun run build`: Build static files
+- `bun run dev`: Run local dev server (default `http://localhost:3000`)
+- `bun run clean`: Remove `dist` and `.cache`
 
-```bash
-bun run blog [build|dev|clean] [options]
-```
+Common options:
 
-기본 명령
-- `bun run build` : 정적 사이트 빌드
-- `bun run dev` : 개발 서버 실행 + 변경 감지
-- `bun run clean` : `dist`와 `.cache` 삭제
-
-옵션
-- `--vault <path>`: 마크다운 루트 디렉터리 (기본: `.`)
-- `--out <path>`: 출력 디렉터리 (기본: `dist`)
-- `--exclude <glob>`: 제외 패턴 (반복 가능, 기본 포함: `.obsidian/**`)
-- `--new-within-days <n>`: NEW 배지 기준 일수 (기본: `7`)
-- `--recent-limit <n>`: Recent 가상 폴더 노출 개수 (기본: `5`)
-- `--menu-config <path>`: 상단 고정 메뉴를 JSON 파일로 임시 덮어쓰기(선택)
-- `--port <n>`: dev 서버 포트 (기본: `3000`)
-
-**릴리즈 단일파일 배포 (GitHub Actions)**
-- 워크플로우 파일: `.github/workflows/release-single-file.yml`
-- 동작: `bun run build` 결과인 `dist`를 단일 `.tar.gz` 파일로 묶어 Release asset으로 업로드
-- 자동 실행: `v*` 태그 푸시 시 실행 (예: `v0.1.0`)
-- 수동 실행: `Actions > Release Single File > Run workflow`에서 `tag`(필수), `asset_name`(선택) 입력
-
-릴리즈 태그 생성 예시
-```bash
-git tag v0.1.0
-git push origin v0.1.0
-```
+- `--vault <path>`: Markdown root directory (default `.`)
+- `--out <path>`: Output directory (default `dist`)
+- `--exclude <glob>`: Add exclude pattern (repeatable)
+- `--port <n>`: Dev server port (default `3000`)
 
-**bunx 배포 (npm publish)**
-- 워크플로우 파일: `.github/workflows/publish-bunx.yml`
-- 동작: `v*` 태그 푸시 시 npm에 패키지 publish (`bun publish`)
-- 전제: GitHub 저장소 `Settings > Secrets and variables > Actions`에 `NPM_TOKEN` 추가
-- 검증: 태그 `vX.Y.Z`와 `package.json`의 `version`이 다르면 배포 실패
+Examples:
 
-사용자 실행 예시
 ```bash
-bunx @limcpf/everything-is-a-markdown build --vault ./vault --out ./dist
-bunx @limcpf/everything-is-a-markdown dev --port 3000
+# Run with the sample vault
+bun run dev -- --vault ./test-vault --out ./dist
 
-# 축약 실행 (bin: eiam)
-bunx --package @limcpf/everything-is-a-markdown eiam build --vault ./vault --out ./dist
+# Build
+bun run build -- --vault ./test-vault --out ./dist
 ```
 
-예시
-```bash
-# 다른 볼트 경로로 빌드
-bun run build -- --vault ../vault --out ./dist
+## Markdown Frontmatter
 
-# dev 서버 포트 변경
-bun run dev -- --port 4000
+The key field for publishing is `publish`.
 
-# 제외 패턴 추가
-bun run build -- --exclude "private/**" --exclude "**/drafts/**"
+Required:
 
-# 상단 고정 메뉴 임시 덮어쓰기(선택)
-bun run build -- --menu-config ./menu.config.json
-```
+- `publish: true`  
+  Only documents with this value are included in build output.
 
-**설정 파일**
-프로젝트 루트에 `blog.config.ts|js|mjs|cjs`를 두면 CLI 옵션과 병합됩니다.
-
-```ts
-// blog.config.ts
-export default {
-  vaultDir: "./vault",
-  outDir: "dist",
-  exclude: [".obsidian/**", "private/**"],
-  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"
-    gfm: true,
-    highlight: {
-      theme: "github-dark",
-    },
-  },
-};
-```
+Optional:
+
+- `draft: true`  
+  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: "..."`  
+  Short summary.
+- `tags: ["tag1", "tag2"]`  
+  String array.
+- `date: "YYYY-MM-DD"` or `createdDate: "..."`  
+  Created date.
+- `updatedDate: "..."` or `modifiedDate: "..."` or `lastModified: "..."`  
+  Updated date.
 
-고정 메뉴 설정 메모
-- `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`은 생성되지 않습니다.
-
-**콘텐츠 작성 규칙**
-- `publish: true`인 문서만 출력됩니다.
-- `draft: true`면 출력에서 제외됩니다.
-- `branch`를 지정하면 해당 브랜치 필터에서만 노출됩니다.
-- `branch`가 없으면 "브랜치 분류 없음"으로 간주되어 기본 브랜치에서만 노출됩니다.
-- 기본 브랜치 뷰는 `dev + 분류 없음`이며, 다른 브랜치는 해당 브랜치 글만 노출됩니다.
-- `title`이 없으면 파일명에서 자동 생성됩니다.
-- 생성일은 `date` 또는 `createdDate`를 사용합니다.
-- 수정일은 `updatedDate`(`modifiedDate`/`lastModified`도 허용)를 사용합니다.
-- 생성/수정일은 frontmatter에 값이 있을 때만 본문 메타에 표시됩니다.
-- `tags`는 문자열 배열로 작성합니다.
+## Frontmatter Examples
+
+Published document:
 
 ```md
 ---
 publish: true
+prefix: "DEV-01"
 branch: dev
-title: My Post
-date: "2024-10-24"
-updatedDate: "2024-10-25T14:30:00"
-description: Short summary
-tags: ["dev", "blog"]
+title: Setup Guide
+date: "2024-09-15"
+updatedDate: "2024-09-20T09:30:00"
+description: How to set up your development environment
+tags: ["tutorial", "setup"]
 ---
 
-# Hello
-본문 내용...
+# Setup Guide
 ```
 
-**출력 구조**
-- `dist/manifest.json`: 트리, 문서 메타, 라우팅 정보
-- `dist/content/*.html`: 각 문서 본문 HTML
-- `dist/_app/index.html`: 앱 셸
-- `dist/<문서 slug 경로>/index.html`: 각 문서 경로
-- `dist/assets/app.js`, `dist/assets/app.css`: 런타임 UI
-
-**SEO/A11y 생성 결과**
-- 라우트별 HTML(`index.html`, `about/index.html`, `posts/2024/setup-guide/index.html` 등)에 route-specific `<title>`, description, canonical, Open Graph/Twitter meta가 주입됩니다.
-- 각 라우트에 JSON-LD(`application/ld+json`)가 포함됩니다.
-- `seo.siteUrl` 설정 시에만 `robots.txt`, `sitemap.xml`이 생성됩니다.
-  - `robots.txt`는 `Sitemap: <canonical sitemap url>`을 포함합니다.
-  - `sitemap.xml`은 `/` + 게시된 문서 라우트들을 canonical URL로 직렬화합니다 (`seo.pathBase` 반영).
-- 접근성 기본값:
-  - skip link: `본문으로 건너뛰기` (`href="#viewer-panel"`)
-  - live region: `#a11y-status` (`aria-live="polite"`, `aria-atomic="true"`)
-  - reduced motion: `prefers-reduced-motion: reduce`에서 `.status-dot` pulse 애니메이션 비활성화
+Private document (excluded):
 
-**검증 명령 (복붙용)**
+```md
+---
+publish: false
+title: Internal Notes
+---
+```
 
-1) Temp CWD 기반으로 SEO OFF/ON 빌드 (repo 설정 파일 비오염)
+Draft document:
 
-```bash
-REPO="$(pwd)"
-TMP_NO="$(mktemp -d)"
-TMP_YES="$(mktemp -d)"
-TMP_OUT="$(mktemp -d)"
-
-# SEO OFF (blog.config.* 없음)
-(cd "$TMP_NO" && bun "$REPO/src/cli.ts" build --vault "$REPO/test-vault" --out "$TMP_OUT/no-seo-out")
-
-# SEO ON (temp blog.config.mjs 사용)
-cat > "$TMP_YES/blog.config.mjs" <<'EOF'
-export default {
-  seo: {
-    siteUrl: "https://docs.example.com",
-    pathBase: "/kb"
-  }
-};
-EOF
-(cd "$TMP_YES" && bun "$REPO/src/cli.ts" build --vault "$REPO/test-vault" --out "$TMP_OUT/with-seo-out")
+```md
+---
+publish: true
+draft: true
+title: Work In Progress
+---
 ```
 
-2) 라우트별 head/JSON-LD + robots/sitemap assert
+## bunx (Optional)
 
 ```bash
-bun -e 'import { existsSync, readFileSync } from "node:fs";
-const out = process.env.OUT;
-const noSeoOut = `${out}/no-seo-out`;
-const withSeoOut = `${out}/with-seo-out`;
-const pages = [
-  ["index", `${withSeoOut}/index.html`, "https://docs.example.com/kb/"],
-  ["about", `${withSeoOut}/about/index.html`, "https://docs.example.com/kb/about/"],
-  ["post", `${withSeoOut}/posts/2024/setup-guide/index.html`, "https://docs.example.com/kb/posts/2024/setup-guide/"],
-];
-for (const [name, file, canonical] of pages) {
-  const html = readFileSync(file, "utf8");
-  console.log(`${name}: canonical=${html.includes(`<link rel="canonical" href="${canonical}" />`)} og:url=${html.includes(`<meta property="og:url" content="${canonical}" />`)} jsonld=${/<script type="application\/ld\+json">[\s\S]*<\/script>/.test(html)}`);
-}
-console.log(`no-seo robots=${existsSync(`${noSeoOut}/robots.txt`)}`);
-console.log(`no-seo sitemap=${existsSync(`${noSeoOut}/sitemap.xml`)}`);
-console.log(`with-seo robots=${existsSync(`${withSeoOut}/robots.txt`)}`);
-console.log(`with-seo sitemap=${existsSync(`${withSeoOut}/sitemap.xml`)}`);
-' OUT="$TMP_OUT"
+bunx @limcpf/everything-is-a-markdown build --vault ./vault --out ./dist
+bunx @limcpf/everything-is-a-markdown dev --port 3000
 ```
 
-3) Playwright MCP 최소 키보드/포커스 + reduced motion 확인 (OpenCode)
-
-```text
-static server: (cd "$TMP_OUT/with-seo-out" && python3 -m http.server 4173 --bind 127.0.0.1)
-
-browser_navigate: http://127.0.0.1:4173/
-
-browser_run_code:
-async (page) => {
-  await page.keyboard.press('Tab');
-  const skip = await page.evaluate(() => document.activeElement?.className);
-  await page.keyboard.press('Enter');
-  const focus = await page.evaluate(() => ({ hash: window.location.hash, id: document.activeElement?.id }));
-  await page.emulateMedia({ reducedMotion: 'no-preference' });
-  const normal = await page.evaluate(() => getComputedStyle(document.querySelector('.status-dot')).animationName);
-  await page.emulateMedia({ reducedMotion: 'reduce' });
-  const reduced = await page.evaluate(() => getComputedStyle(document.querySelector('.status-dot')).animationName);
-  return { skip, focus, normal, reduced };
-}
-```
+## License
 
-**추가로 필요한 문서 목록**
-- `LICENSE`: 라이선스 명시
-- `CHANGELOG.md`: 버전별 변경 이력
-- `CONTRIBUTING.md`: 개발/기여 가이드와 브랜치 규칙
-- `CODE_OF_CONDUCT.md`: 커뮤니티 행동 강령
-- `SECURITY.md`: 보안 취약점 신고 절차
-- `docs/CONFIG.md`: 설정 옵션 상세 레퍼런스
-- `docs/ARCHITECTURE.md`: 빌드 파이프라인과 런타임 구조 설명
-- `docs/DEPLOYMENT.md`: 정적 호스팅 배포 가이드
-- `docs/TROUBLESHOOTING.md`: 자주 발생하는 문제와 해결 방법
-- `docs/FAQ.md`: 사용자 FAQ
+MIT. See `LICENSE`.

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@limcpf/everything-is-a-markdown",
-  "version": "0.4.1",
+  "version": "0.4.3",
+  "license": "MIT",
   "private": false,
   "type": "module",
   "bin": {

package/src/build.ts

@@ -20,7 +20,7 @@ import {
   toRoute,
 } from "./utils";
 
-const CACHE_VERSION = 2;
+const CACHE_VERSION = 3;
 const CACHE_DIR_NAME = ".cache";
 const CACHE_FILE_NAME = "build-index.json";
 const DEFAULT_BRANCH = "dev";
@@ -121,6 +121,7 @@ function normalizeCachedSourceEntry(value: unknown): CachedSourceEntry | null {
   const publish = value.publish === true;
   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 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;
@@ -142,6 +143,7 @@ function normalizeCachedSourceEntry(value: unknown): CachedSourceEntry | null {
     publish,
     draft,
     title,
+    prefix,
     date,
     updatedDate,
     description,
@@ -329,6 +331,25 @@ function pickDocUpdatedDate(frontmatter: Record<string, unknown>, raw: string):
   return pickFrontmatterDate(frontmatter, raw, ["updatedDate", "modifiedDate", "lastModified"]);
 }
 
+function pickDocPrefix(frontmatter: Record<string, unknown>, raw: string): string | undefined {
+  const literal = extractFrontmatterScalar(raw, "prefix");
+  if (literal) {
+    return literal;
+  }
+
+  const value = frontmatter.prefix;
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+  }
+
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return String(value);
+  }
+
+  return undefined;
+}
+
 function appendRouteSuffix(route: string, suffix: string): string {
   const clean = route.replace(/^\/+/, "").replace(/\/+$/, "");
   if (!clean) {
@@ -431,6 +452,7 @@ function toCachedSourceEntry(raw: string, parsed: matter.GrayMatterFile<string>)
     publish: parsed.data.publish === true,
     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),
     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,
@@ -460,6 +482,7 @@ function toDocRecord(
     contentUrl: `/content/${toContentFileName(id)}`,
     fileName,
     title: entry.title ?? makeTitleFromFileName(fileName),
+    prefix: entry.prefix,
     date: entry.date,
     updatedDate: entry.updatedDate,
     description: entry.description,
@@ -589,9 +612,9 @@ function fileNodeFromDoc(doc: DocRecord): FileNode {
     name: doc.fileName,
     id: doc.id,
     title: doc.title,
+    prefix: doc.prefix,
     route: doc.route,
     contentUrl: doc.contentUrl,
-    mtime: doc.mtimeMs,
     isNew: doc.isNew,
     tags: doc.tags,
     description: doc.description,
@@ -633,7 +656,32 @@ function isNewByFrontmatterDate(date: string | undefined, newThreshold: number):
 }
 
 function getRecentSortEpochMs(doc: DocRecord): number {
-  return parseDateToEpochMs(doc.date) ?? doc.mtimeMs;
+  return parseDateToEpochMs(doc.updatedDate) ?? parseDateToEpochMs(doc.date);
+}
+
+function compareByRecentDateThenPath(left: DocRecord, right: DocRecord): number {
+  const leftEpoch = getRecentSortEpochMs(left);
+  const rightEpoch = getRecentSortEpochMs(right);
+
+  if (leftEpoch != null && rightEpoch != null) {
+    const byDate = rightEpoch - leftEpoch;
+    if (byDate !== 0) {
+      return byDate;
+    }
+  } else if (leftEpoch != null && rightEpoch == null) {
+    return -1;
+  } else if (leftEpoch == null && rightEpoch != null) {
+    return 1;
+  }
+
+  return left.relNoExt.localeCompare(right.relNoExt, "ko-KR");
+}
+
+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;
+  const byRoute = candidates.find((doc) => doc.route === "/index/");
+  return byRoute ?? candidates[0] ?? null;
 }
 
 function buildPinnedMenuFolder(docs: DocRecord[], options: BuildOptions): FolderNode | null {
@@ -697,19 +745,7 @@ function buildTree(docs: DocRecord[], options: BuildOptions): TreeNode[] {
   sortTree(root.children);
 
   const recentChildren = [...docs]
-    .sort((left, right) => {
-      const byDate = getRecentSortEpochMs(right) - getRecentSortEpochMs(left);
-      if (byDate !== 0) {
-        return byDate;
-      }
-
-      const byMtime = right.mtimeMs - left.mtimeMs;
-      if (byMtime !== 0) {
-        return byMtime;
-      }
-
-      return left.relNoExt.localeCompare(right.relNoExt, "ko-KR");
-    })
+    .sort(compareByRecentDateThenPath)
     .slice(0, options.recentLimit)
     .map((doc) => fileNodeFromDoc(doc));
 
@@ -735,21 +771,19 @@ function buildManifest(docs: DocRecord[], tree: TreeNode[], options: BuildOption
     routeMap[doc.route] = doc.id;
   }
 
-  const docsForManifest = [...docs]
-    .sort((a, b) => b.mtimeMs - a.mtimeMs)
-    .map((doc) => ({
-      id: doc.id,
-      route: doc.route,
-      title: doc.title,
-      mtime: doc.mtimeMs,
-      date: doc.date,
-      updatedDate: doc.updatedDate,
-      tags: doc.tags,
-      description: doc.description,
-      isNew: doc.isNew,
-      contentUrl: doc.contentUrl,
-      branch: doc.branch,
-    }));
+  const docsForManifest = docs.map((doc) => ({
+    id: doc.id,
+    route: doc.route,
+    title: doc.title,
+    prefix: doc.prefix,
+    date: doc.date,
+    updatedDate: doc.updatedDate,
+    tags: doc.tags,
+    description: doc.description,
+    isNew: doc.isNew,
+    contentUrl: doc.contentUrl,
+    branch: doc.branch,
+  }));
 
   const branchSet = new Set<string>([DEFAULT_BRANCH]);
   for (const doc of docs) {
@@ -984,6 +1018,10 @@ function normalizeTags(tags: string[]): string[] {
 function renderInitialMeta(doc: DocRecord): string {
   const items: string[] = [];
 
+  if (doc.prefix) {
+    items.push(`<span class="meta-item meta-prefix">${escapeHtmlAttribute(doc.prefix)}</span>`);
+  }
+
   const createdAt = formatMetaDateTime(doc.date);
   if (createdAt) {
     items.push(
@@ -991,13 +1029,6 @@ function renderInitialMeta(doc: DocRecord): string {
     );
   }
 
-  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(" ");
@@ -1047,7 +1078,7 @@ async function writeShellPages(
   runtimeAssets: RuntimeAssets,
   contentByDocId: Map<string, string>,
 ): Promise<void> {
-  const indexDoc = docs[0] ?? null;
+  const indexDoc = pickHomeDoc(docs);
   const indexOutputPath = "index.html";
   const indexInitialView = indexDoc ? buildInitialView(indexDoc, docs, contentByDocId.get(indexDoc.id) ?? "") : null;
   const shell = renderAppShellHtml(

package/src/runtime/app.css

@@ -60,6 +60,8 @@
   --sidebar-mobile-shadow: 0 24px 48px rgba(76, 79, 105, 0.2);
   --accent-hover: #7030d0;
   --accent-strong: #6732ca;
+  --badge-new-bg: var(--latte-red);
+  --badge-new-fg: #ffffff;
   --desktop-sidebar-default: 420px;
   --desktop-sidebar-min: 320px;
   --desktop-viewer-min: 680px;
@@ -103,6 +105,8 @@
   --sidebar-mobile-shadow: 0 24px 48px rgba(0, 0, 0, 0.45);
   --accent-hover: #a985f6;
   --accent-strong: #dfcbff;
+  --badge-new-bg: var(--mocha-red);
+  --badge-new-fg: var(--mocha-crust);
 }
 
 * {
@@ -478,6 +482,14 @@ a:hover {
   color: var(--latte-overlay0);
 }
 
+.tree-prefix {
+  flex: 0 0 auto;
+  font-size: 0.68rem;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  color: var(--latte-subtext1);
+}
+
 .tree-label {
   flex: 1;
   overflow: hidden;
@@ -526,8 +538,8 @@ a:hover {
   letter-spacing: 0.03em;
   padding: 2px 6px;
   border-radius: 999px;
-  color: white;
-  background: var(--latte-red);
+  color: var(--badge-new-fg);
+  background: var(--badge-new-bg);
 }
 
 /* Active badge */
@@ -582,7 +594,7 @@ a:hover {
 
 .status-encoding {
   font-family: ui-monospace, "SFMono-Regular", Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
-  color: var(--latte-overlay0);
+  color: var(--latte-subtext1);
 }
 
 .sidebar-footer-actions {
@@ -829,7 +841,7 @@ body.mobile-toggle-left .mobile-menu-toggle {
   min-height: 22px;
   font-size: 0.85rem;
   font-family: ui-monospace, "SFMono-Regular", Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
-  color: var(--latte-subtext0);
+  color: var(--latte-subtext1);
 }
 
 .meta-item {
@@ -843,6 +855,13 @@ body.mobile-toggle-left .mobile-menu-toggle {
   color: var(--latte-overlay0);
 }
 
+.meta-prefix {
+  font-size: 0.74rem;
+  font-weight: 700;
+  letter-spacing: 0.03em;
+  color: var(--latte-subtext1);
+}
+
 .meta-tags {
   color: var(--latte-lavender);
 }
@@ -858,7 +877,7 @@ body.mobile-toggle-left .mobile-menu-toggle {
   max-width: 72ch;
   margin: 0 auto;
   text-wrap: pretty;
-  color: var(--latte-subtext0);
+  color: var(--latte-subtext1);
 }
 
 .viewer-content h1,
@@ -915,7 +934,7 @@ body.mobile-toggle-left .mobile-menu-toggle {
   background: rgba(230, 233, 239, 0.5);
   border-radius: 0 8px 8px 0;
   font-style: normal;
-  color: var(--latte-subtext0);
+  color: var(--latte-subtext1);
 }
 
 /* Inline code */

package/src/runtime/app.js

@@ -217,6 +217,13 @@ function buildBranchView(manifest, branch, defaultBranch) {
   };
 }
 
+function pickHomeRoute(view) {
+  if (view.routeMap["/index/"]) {
+    return "/index/";
+  }
+  return view.docs[0]?.route || "/";
+}
+
 function loadExpandedSet() {
   try {
     const raw = localStorage.getItem(EXPANDED_KEY);
@@ -614,8 +621,11 @@ function createFileNode(node, fileRowsById, depth = 0) {
   row.dataset.fileId = node.id;
   row.style.setProperty("--tree-depth", String(depth));
 
+  const prefix = typeof node.prefix === "string" ? node.prefix.trim() : "";
+  const prefixHtml = prefix ? `<span class="tree-prefix">${escapeHtmlAttr(prefix)}</span>` : "";
+  const label = escapeHtmlAttr(node.title || node.name);
   const newBadge = node.isNew ? `<span class="badge-new">NEW</span>` : "";
-  row.innerHTML = `<span class="material-symbols-outlined">article</span><span class="tree-label">${node.title || node.name}</span>${newBadge}`;
+  row.innerHTML = `<span class="material-symbols-outlined">article</span>${prefixHtml}<span class="tree-label">${label}</span>${newBadge}`;
   fileRowsById.set(node.id, row);
 
   return row;
@@ -684,6 +694,10 @@ function renderBreadcrumb(route) {
 function renderMeta(doc) {
   const items = [];
 
+  if (typeof doc.prefix === "string" && doc.prefix.trim().length > 0) {
+    items.push(`<span class="meta-item meta-prefix">${escapeHtmlAttr(doc.prefix)}</span>`);
+  }
+
   const createdAt = formatMetaDateTime(doc.date);
   if (createdAt) {
     items.push(
@@ -691,13 +705,6 @@ function renderMeta(doc) {
     );
   }
 
-  const updatedAt = formatMetaDateTime(doc.updatedDate);
-  if (updatedAt) {
-    items.push(
-      `<span class="meta-item"><span class="material-symbols-outlined">schedule</span>updated ${escapeHtmlAttr(updatedAt)}</span>`,
-    );
-  }
-
   const tags = normalizeTags(doc.tags);
   if (tags.length > 0) {
     const tagsStr = tags.map((tag) => `#${escapeHtmlAttr(tag)}`).join(" ");
@@ -882,11 +889,15 @@ async function start() {
     }
 
     if (!isCompactLayout()) {
-      sidebar.removeAttribute("aria-hidden");
+      sidebar.removeAttribute("inert");
       return;
     }
 
-    sidebar.setAttribute("aria-hidden", String(!isOpen));
+    if (isOpen) {
+      sidebar.removeAttribute("inert");
+    } else {
+      sidebar.setAttribute("inert", "");
+    }
   };
 
   const openSidebar = () => {
@@ -1452,7 +1463,7 @@ async function start() {
       return;
     }
 
-    const fallbackRoute = view.docs[0]?.route || "/";
+    const fallbackRoute = pickHomeRoute(view);
     await state.navigate(fallbackRoute, true);
   };
 
@@ -1461,7 +1472,7 @@ async function start() {
   renderTree(state);
 
   const currentRoute = resolveRouteFromLocation(view.routeMap);
-  const initialRoute = currentRoute === "/" ? view.docs[0]?.route || "/" : currentRoute;
+  const initialRoute = currentRoute === "/" ? pickHomeRoute(view) : currentRoute;
   handleLayoutChange();
   await state.navigate(initialRoute, currentRoute === "/" && initialRoute !== "/");
 

package/src/types.ts

@@ -82,6 +82,7 @@ export interface DocRecord {
   contentUrl: string;
   fileName: string;
   title: string;
+  prefix?: string;
   date?: string;
   updatedDate?: string;
   description?: string;
@@ -99,9 +100,9 @@ export interface FileNode {
   name: string;
   id: string;
   title: string;
+  prefix?: string;
   route: string;
   contentUrl: string;
-  mtime: number;
   isNew: boolean;
   tags: string[];
   description?: string;
@@ -134,8 +135,8 @@ export interface Manifest {
     id: string;
     route: string;
     title: string;
+    prefix?: string;
     contentUrl: string;
-    mtime: number;
     date?: string;
     updatedDate?: string;
     tags: string[];
@@ -156,6 +157,7 @@ export interface BuildCache {
       publish: boolean;
       draft: boolean;
       title?: string;
+      prefix?: string;
       date?: string;
       updatedDate?: string;
       description?: string;