@open330/kiwimu 0.4.1 → 0.8.0

package/README.md

@@ -8,6 +8,7 @@
 
 전공책, PDF, 웹 콘텐츠를 넣으면 — LLM이 챕터/개념별로 분석하여 상호 링크된 학습 위키를 자동 생성합니다.
 
+[![npm](https://img.shields.io/npm/v/@open330/kiwimu?style=flat-square&color=cb3837&logo=npm)](https://www.npmjs.com/package/@open330/kiwimu)
 [![Bun](https://img.shields.io/badge/Bun-1.0+-fbf0df?style=flat-square&logo=bun&logoColor=black)](https://bun.sh)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://typescriptlang.org)
 [![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)
@@ -16,16 +17,28 @@
 
 ---
 
+## 30초 데모 체험
+
+API key 없이 바로 체험할 수 있습니다:
+
+```bash
+mkdir my-wiki && cd my-wiki
+bunx @open330/kiwimu init --demo
+# → 양자역학 샘플 위키 + 학습 퀴즈가 즉시 생성됩니다
+# → http://localhost:8000 에서 확인하세요
+```
+
+---
+
 ## Quickstart for Agents
 
 <div><img src="https://quickstart-for-agents.vercel.app/api/header.svg?theme=claude-code&logo=kiwimu&title=Set+up+a+learning+wiki+from+any+textbook+or+URL&lang=Agents&font=mono&mascot=hat" width="100%" /></div>
 
 ```
-git clone https://github.com/Open330/kiwimu.git && cd kiwimu && bun install
 mkdir my-wiki && cd my-wiki
-bunx kiwimu init
-bunx kiwimu add "<YOUR_URL_OR_PDF>"
-bunx kiwimu serve
+bunx @open330/kiwimu init
+bunx @open330/kiwimu add "<YOUR_URL_OR_PDF>"
+bunx @open330/kiwimu serve
 ```
 
 <div><img src="https://quickstart-for-agents.vercel.app/api/footer.svg?theme=claude-code&text=copy+this+prompt+%C2%B7+paste+into+your+agent+%C2%B7+get+a+learning+wiki&font=mono" width="100%" /></div>
@@ -40,10 +53,14 @@ Kiwi Mu는 LLM을 활용해 이 연결을 **자동으로** 만들어, 지식을
 - **LLM 기반 문서 분석** — 챕터/섹션 구조를 보존한 원본 페이지 + 핵심 개념별 자동 생성 페이지
 - **원본/개념 분리** — 📖 원본 문서와 📝 개념 문서를 시각적으로 구분
 - **자동 상호 링크** — 원본↔개념 간 유기적 cross-link + 외부 참고 자료 (Wikipedia 등)
+- **학습 퀴즈** — 개념 페이지 기반 빈칸 채우기 / OX / 단답형 퀴즈 자동 생성
 - **지식 그래프** — D3.js 인터랙티브 그래프 (원본: 파란색, 개념: 초록색)
+- **데모 모드** — API key 없이 `--demo`로 즉시 체험
+- **다양한 파일 지원** — URL, PDF, DOCX, PPTX, PPT, DOC, KEY, RTF
+- **4개 LLM 프로바이더** — Google Gemini, Azure OpenAI, OpenAI, Anthropic
+- **다크 모드** — 시스템 테마에 자동 대응
+- **모바일 지원** — 햄버거 메뉴 + 슬라이드 사이드바
 - **웹 UI** — 브라우저에서 문서 추가, 설정 변경, 빌드 실행
-- **다양한 파일 지원** — URL, PDF, DOCX, PPTX, PPT, DOC, KEY
-- **다중 LLM 프로바이더** — Google Gemini, Azure OpenAI, OpenAI, Anthropic
 - **토큰 사용량 추적** — API 호출 수, 토큰, 예상 비용을 웹에서 확인
 - **원클릭 배포** — GitHub Pages / Vercel
 
@@ -52,15 +69,32 @@ Kiwi Mu는 LLM을 활용해 이 연결을 **자동으로** 만들어, 지식을
 ### 설치
 
 ```bash
-git clone https://github.com/Open330/kiwimu.git
-cd kiwimu && bun install
+# npm/bunx로 바로 사용 (설치 불필요)
+bunx @open330/kiwimu init
+
+# 또는 글로벌 설치
+bun add -g @open330/kiwimu
+```
+
+### 데모 모드 (API key 불필요)
+
+```bash
+mkdir my-wiki && cd my-wiki
+bunx @open330/kiwimu init --demo
 ```
 
+양자역학 샘플 위키가 생성되어 바로 체험할 수 있습니다:
+- 📖 원본 문서 + 📝 개념 페이지
+- 🔗 자동 상호 링크
+- 📊 지식 그래프
+- 📝 학습 퀴즈
+- 🎲 임의 문서 탐험
+
 ### 프로젝트 생성 (Interactive CLI)
 
 ```bash
 mkdir my-wiki && cd my-wiki
-bunx kiwimu init
+bunx @open330/kiwimu init
 ```
 
 Interactive 프롬프트가 실행됩니다:
@@ -86,68 +120,68 @@ Interactive 프롬프트가 실행됩니다:
 🥝 'Radio Astronomy Wiki' 위키가 생성되었습니다!
 ```
 
-이름을 바로 지정할 수도 있습니다:
-
-```bash
-bunx kiwimu init "My Study Wiki"
-```
-
 ### 문서 추가
 
 ```bash
 # URL 추가
-bunx kiwimu add "https://www.cv.nrao.edu/~sransom/web/Ch1.html"
+bunx @open330/kiwimu add "https://www.cv.nrao.edu/~sransom/web/Ch1.html"
 
-# PDF 추가
-bunx kiwimu add textbook.pdf
+# 파일 추가 (PDF, DOCX, PPTX, DOC, PPT, KEY, RTF)
+bunx @open330/kiwimu add textbook.pdf
+bunx @open330/kiwimu add lecture.pptx
 ```
 
 LLM이 문서를 분석하여:
 1. 📖 **원본 페이지** — 원래 챕터/섹션 구조 보존
 2. 📝 **개념 페이지** — 핵심 용어·정의·법칙 자동 생성
 3. 🔗 **Cross-link** — 원본↔개념 간 유기적 연결
+4. 📝 **퀴즈** — 개념별 학습 퀴즈 자동 생성
+
+### 학습 퀴즈
+
+```bash
+# 터미널에서 퀴즈 풀기
+bunx @open330/kiwimu quiz
+
+# 문제 수 지정
+bunx @open330/kiwimu quiz -n 10
+```
+
+웹에서도 `http://localhost:8000/quiz.html`에서 카드 플립 방식으로 퀴즈를 풀 수 있습니다.
 
 ### 빌드 및 서버
 
 ```bash
 # 정적 사이트 빌드
-bunx kiwimu build
+bunx @open330/kiwimu build
 
 # 로컬 서버 실행 (웹에서 문서 추가 가능)
-bunx kiwimu serve
+bunx @open330/kiwimu serve
 # → http://localhost:8000
 
 # 포트 변경
-bunx kiwimu serve -p 3000
-
-# 네트워크에 공개 (0.0.0.0)
-bunx kiwimu serve --host 0.0.0.0
+bunx @open330/kiwimu serve -p 3000
 ```
 
-### 웹 UI에서 문서 추가
-
-`kiwimu serve` 실행 후 http://localhost:8000 에서:
-- **🔗 URL 탭** — URL 입력 후 추가
-- **📄 파일 업로드 탭** — PDF, DOCX, PPTX 등 드래그앤드롭 업로드
-- 진행 상태 실시간 표시, 완료 시 자동 새로고침
-
 ### 관리 페이지
 
-http://localhost:8000/admin 에서:
+`kiwimu serve` 실행 후 콘솔에 표시되는 admin URL로 접속:
 - 위키 이름 변경
 - LLM 프로바이더/모델/API Key 설정
 - 토큰 사용량 및 예상 비용 확인
-- 등록된 소스 목록
+- 파일 업로드 (PDF, DOCX, PPTX 등)
+- URL 추가
 - 수동 빌드 실행
+- 페르소나 관리
 
 ### 배포
 
 ```bash
 # GitHub Pages (기본)
-bunx kiwimu deploy
+bunx @open330/kiwimu deploy
 
 # Vercel
-bunx kiwimu deploy --target vercel
+bunx @open330/kiwimu deploy --target vercel
 ```
 
 ## Commands
@@ -155,10 +189,13 @@ bunx kiwimu deploy --target vercel
 | 명령 | 설명 |
 |------|------|
 | `kiwimu init [name]` | 새 위키 프로젝트 생성 (interactive CLI) |
-| `kiwimu add <source>` | URL 또는 파일 추가 (LLM 분석 + 링크 생성) |
+| `kiwimu init --demo` | 샘플 데이터로 즉시 체험 (API key 불필요) |
+| `kiwimu add <source>` | URL 또는 파일 추가 (PDF, DOCX, PPTX, DOC, PPT, KEY, RTF) |
 | `kiwimu build` | 정적 위키 사이트 빌드 |
-| `kiwimu serve [-p port] [--host host]` | 웹 서버 실행 (문서 추가/관리 가능) |
-| `kiwimu deploy` | GitHub Pages / Vercel에 배포 |
+| `kiwimu serve [-p port]` | 웹 서버 실행 (문서 추가/관리 가능) |
+| `kiwimu quiz [-n count]` | 터미널에서 학습 퀴즈 풀기 |
+| `kiwimu expand [--provider]` | LLM으로 문서 내용 확장 (선택) |
+| `kiwimu deploy [--target]` | GitHub Pages / Vercel에 배포 |
 | `kiwimu status` | 현재 위키 상태 표시 |
 
 ## Supported File Formats
@@ -178,36 +215,40 @@ bunx kiwimu deploy --target vercel
 |-----------|----------|------|
 | **Google Gemini** | `gemini-2.0-flash-lite` | [무료 API key](https://aistudio.google.com/) |
 | Azure OpenAI | `gpt-5-nano` | Azure 구독 필요 |
-| OpenAI | `gpt-4o-mini` | API key 필요 |
+| OpenAI | `gpt-4o` | API key 필요 |
 | Anthropic | `claude-sonnet-4-20250514` | API key 필요 |
 
 ## Architecture
 
 ```
-소스 (URL / PDF / DOCX / PPTX)
+소스 (URL / PDF / DOCX / PPTX / DOC / PPT / KEY / RTF)
     ↓
-[ Ingest ]    ── Cheerio / pdf-parse / mammoth / jszip
+[ Ingest ]      ── Cheerio / pdf-parse / mammoth / jszip / textutil
     ↓
-[ Phase 1 ]   ── LLM: 원본 구조 추출 (📖 원본 페이지)
+[ Phase 1 ]     ── LLM: 원본 구조 추출 (📖 원본 페이지) — 병렬 처리 (concurrency=3)
     ↓
-[ Phase 2 ]   ── LLM: 개념 추출 (📝 개념 페이지)
+[ Phase 2 ]     ── LLM: 개념 추출 (📝 개념 페이지)
     ↓
-[ Phase 3 ]   ── [[wiki link]] 해석 + 원본↔개념 cross-link
+[ Phase 2.5 ]   ── LLM: 학습 퀴즈 자동 생성 (📝 퀴즈) — 병렬 처리
     ↓
-[ Build ]     ── 정적 HTML 생성 (탭 사이드바, KaTeX, 지식 그래프)
+[ Phase 3 ]     ── [[wiki link]] 해석 + 원본↔개념 cross-link
     ↓
-[ Deploy ]    ── GitHub Pages / Vercel
+[ Build ]       ── 정적 HTML (사이드바, KaTeX, 지식 그래프, 퀴즈, 다크 모드)
+    ↓
+[ Deploy ]      ── GitHub Pages / Vercel
 ```
 
 ```
 project-dir/
 ├── kiwi.toml          # 프로젝트 + LLM 설정
-├── kiwi.db            # SQLite (문서, 링크, 사용량)
+├── kiwi.db            # SQLite (문서, 링크, 퀴즈, 사용량)
 ├── uploads/           # 업로드된 파일
 └── _site/             # 빌드 결과
-    ├── index.html     # 홈 (문서 추가 UI + 사용량 대시보드)
+    ├── index.html     # 홈 (문서 목록)
     ├── graph.html     # 지식 그래프
+    ├── quiz.html      # 학습 퀴즈
     ├── wiki/          # 각 문서 페이지
+    │   └── random.html  # 임의 문서
     ├── static/        # CSS, JS, 로고
     └── search-index.json
 ```
@@ -220,11 +261,19 @@ project-dir/
 - **Cheerio** — 웹 페이지 파싱
 - **Mammoth** — DOCX 파싱
 - **JSZip** — PPTX 파싱
-- **Marked** — Markdown → HTML
+- **Marked** + **sanitize-html** — Markdown → 안전한 HTML
 - **D3.js** — 지식 그래프
 - **KaTeX** — 수학 수식 렌더링
 - **gh-pages** — GitHub Pages 배포
 
+## Security
+
+- Bearer 토큰 인증 (serve 모드)
+- SSRF 방지 (프라이빗 IP 차단, 리다이렉트 재검증)
+- Path Traversal 방지 (resolve 검증)
+- XSS 방지 (sanitize-html, CSP 헤더, escapeHtml)
+- 파일 업로드 제한 (50MB)
+
 ## License
 
 MIT

package/bin/kiwimu

@@ -1,2 +1,2 @@
 #!/usr/bin/env bun
-await import("../src/index.ts");
+import "../src/index.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open330/kiwimu",
-  "version": "0.4.1",
+  "version": "0.8.0",
   "description": "Turn textbooks, PDFs, and web content into your own interlinked learning wiki powered by LLM",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "bin/**/*",
     "src/**/*",
+    "personas/**/*",
     "assets/**/*",
     "README.md",
     "LICENSE"
@@ -48,6 +49,7 @@
     "mammoth": "^1.12.0",
     "marked": "^15.0.0",
     "pdf-parse": "1.1.1",
+    "sanitize-html": "^2.17.2",
     "smol-toml": "^1.3.1",
     "turndown": "^7.2.0"
   },
@@ -58,6 +60,7 @@
   "devDependencies": {
     "@types/bun": "latest",
     "@types/pdf-parse": "^1.1.5",
+    "@types/sanitize-html": "^2.16.1",
     "@types/turndown": "^5.0.5"
   }
 }

package/personas/namuwiki.json

@@ -0,0 +1,6 @@
+{
+  "name": "나무위키",
+  "description": "나무위키 특유의 문체와 스타일로 문서를 작성합니다",
+  "system_prompt": "당신은 나무위키 스타일의 위키 편집자입니다. 다음 특징을 반드시 지켜주세요:\n\n1. **문체**: 해요체(~입니다/~합니다)를 기본으로 하되, 가끔 반말(~이다/~한다)을 섞어 사용\n2. **유머**: 적절한 곳에 ~~취소선 드립~~, (괄호 안의 부연설명), [1] 각주 스타일의 코멘트를 삽입\n3. **강조**: 중요한 키워드는 **굵게** 처리하고, 핵심 개념은 반복 강조\n4. **서술 톤**: 백과사전적이면서도 친근한 톤. \"~라고 한다\", \"~라고 카더라\" 등의 표현 활용\n5. **구조**: 목차가 잘 정리된 체계적 구조. 소제목을 적극 활용\n6. **부가 정보**: \"여담으로~\", \"참고로~\", \"사실~\" 등의 표현으로 부가 정보 추가\n7. **링크**: 관련 개념에 적극적으로 [[위키 링크]]를 사용\n\n절대 딱딱한 교과서 문체로 쓰지 마세요. 읽는 사람이 재미있게 학습할 수 있도록 작성해주세요.",
+  "content_style": "Write in Korean 나무위키 style:\n- Use 해요체 with occasional 반말 mix\n- Add ~~strikethrough humor~~ and (parenthetical asides)\n- Bold **key terms** generously\n- Use phrases like \"~라고 한다\", \"여담으로~\", \"참고로~\"\n- Be encyclopedic yet friendly and entertaining\n- Structure with clear subsections\n- Use [[wiki links]] actively for related concepts"
+}

package/src/build/renderer.ts

@@ -1,10 +1,11 @@
 import { mkdirSync, rmSync, cpSync, existsSync } from "fs";
 import { join, dirname } from "path";
 import { marked } from "marked";
+import sanitizeHtml from "sanitize-html";
 import type { KiwiConfig } from "../config";
 import type { Store } from "../store";
 import { buildGraphData } from "../pipeline/graph";
-import { renderPage, renderIndex, renderGraph } from "./templates";
+import { renderPage, renderIndex, renderGraph, renderQuizPage } from "./templates";
 
 // Fix internal wiki links: /wiki/slug → /wiki/slug.html
 function fixWikiLinks(html: string): string {
@@ -68,14 +69,28 @@ export async function buildSite(store: Store, config: KiwiConfig, projectRoot: s
   const sourcePages = store.listSourcePages();
   const conceptPages = store.listConceptPages();
   const wikiName = config.project.name;
+  const backlinksMap = store.getAllBacklinksGrouped();
 
   for (const page of pages) {
     let htmlContent = await marked(page.content);
+    htmlContent = sanitizeHtml(htmlContent, {
+      allowedTags: sanitizeHtml.defaults.allowedTags.concat([
+        'img', 'details', 'summary', 'kbd', 'del', 's', 'sup', 'sub',
+        'span', 'div', 'section', 'figure', 'figcaption', 'mark'
+      ]),
+      allowedAttributes: {
+        ...sanitizeHtml.defaults.allowedAttributes,
+        '*': ['id', 'class', 'style'],
+        'img': ['src', 'alt', 'title', 'width', 'height'],
+        'a': ['href', 'title', 'target', 'rel'],
+      },
+      allowedSchemes: ['http', 'https', 'mailto'],
+    });
     htmlContent = fixWikiLinks(htmlContent);
 
     const { body, externalRefs } = extractExternalRefs(htmlContent);
     const toc = generateToc(page.content);
-    const backlinks = store.getBacklinks(page.id).map((bl) => ({
+    const backlinks = (backlinksMap.get(page.id) || []).map((bl) => ({
       slug: bl.slug,
       title: bl.title,
       pageType: bl.page_type,
@@ -116,6 +131,39 @@ export async function buildSite(store: Store, config: KiwiConfig, projectRoot: s
     })
   );
 
+  // Quiz page
+  const quizzes = store.getAllQuizzes();
+  await Bun.write(
+    join(outputDir, "quiz.html"),
+    renderQuizPage({
+      wikiName,
+      quizzes: quizzes.map((q) => ({
+        id: q.id,
+        question: q.question,
+        answer: q.answer,
+        explanation: q.explanation || "",
+        quiz_type: q.quiz_type,
+        page_title: q.page_title,
+        page_slug: q.page_slug,
+      })),
+      sourcePages: sourcePages.map((p) => ({ slug: p.slug, title: p.title })),
+      conceptPages: conceptPages.map((p) => ({ slug: p.slug, title: p.title })),
+    })
+  );
+
+  // Random page redirect
+  mkdirSync(join(wikiDir), { recursive: true });
+  await Bun.write(
+    join(wikiDir, "random.html"),
+    `<!DOCTYPE html><html><head><meta charset="UTF-8"><title>임의 문서</title></head><body><script>
+fetch('/search-index.json').then(r=>r.json()).then(pages=>{
+  const p = pages[Math.floor(Math.random()*pages.length)];
+  if(p) location.href='/wiki/'+p.slug+'.html';
+  else location.href='/';
+});
+</script></body></html>`
+  );
+
   const searchData = pages.map((p) => ({
     slug: p.slug,
     title: p.title,

package/src/build/static/search.js

@@ -5,6 +5,7 @@ document.addEventListener("DOMContentLoaded", async () => {
     if (!input || !dropdown) return;
 
     let searchData = [];
+    let selectedIndex = -1;
     try {
         const resp = await fetch("/search-index.json");
         searchData = await resp.json();
@@ -12,6 +13,12 @@ document.addEventListener("DOMContentLoaded", async () => {
         return;
     }
 
+    function escapeHtml(text) {
+        const div = document.createElement('div');
+        div.textContent = text;
+        return div.innerHTML;
+    }
+
     function fuzzyMatch(query, text) {
         query = query.toLowerCase();
         text = text.toLowerCase();
@@ -31,6 +38,7 @@ document.addEventListener("DOMContentLoaded", async () => {
     }
 
     input.addEventListener("input", () => {
+        selectedIndex = -1;
         const results = search(input.value);
         if (results.length === 0) {
             dropdown.classList.remove("active");
@@ -39,8 +47,8 @@ document.addEventListener("DOMContentLoaded", async () => {
         }
         dropdown.innerHTML = results.map(r =>
             `<a href="/wiki/${r.slug}.html">
-                <strong>${r.title}</strong>
-                <div style="font-size:12px;color:#6c757d;margin-top:2px;">${r.preview.slice(0, 80)}...</div>
+                <strong>${escapeHtml(r.title)}</strong>
+                <div style="font-size:12px;color:#6c757d;margin-top:2px;">${escapeHtml(r.preview.slice(0, 80))}...</div>
             </a>`
         ).join("");
         dropdown.classList.add("active");
@@ -61,6 +69,29 @@ document.addEventListener("DOMContentLoaded", async () => {
         if (e.key === "Escape") {
             dropdown.classList.remove("active");
             input.blur();
+        } else if (e.key === "ArrowDown") {
+            e.preventDefault();
+            const items = dropdown.querySelectorAll("a");
+            selectedIndex = Math.min(selectedIndex + 1, items.length - 1);
+            items.forEach((a, i) => a.classList.toggle("selected", i === selectedIndex));
+            items[selectedIndex]?.scrollIntoView({ block: "nearest" });
+        } else if (e.key === "ArrowUp") {
+            e.preventDefault();
+            const items = dropdown.querySelectorAll("a");
+            selectedIndex = Math.max(selectedIndex - 1, 0);
+            items.forEach((a, i) => a.classList.toggle("selected", i === selectedIndex));
+        } else if (e.key === "Enter" && selectedIndex >= 0) {
+            e.preventDefault();
+            dropdown.querySelectorAll("a")[selectedIndex]?.click();
+        }
+    });
+
+    // Global "/" shortcut to focus search
+    document.addEventListener('keydown', (e) => {
+        if (e.target.tagName === 'INPUT' || e.target.tagName === 'TEXTAREA') return;
+        if (e.key === '/') {
+            e.preventDefault();
+            input.focus();
         }
     });
 });

package/src/build/static/style.css

@@ -24,10 +24,18 @@
     margin: 0;
     padding: 0;
     box-sizing: border-box;
-    border-radius: 0; /* Enforce sharp flat edges everywhere */
     box-shadow: none; /* Enforce no shadows */
 }
 
+/* Targeted border-radius reset for kiwimu elements only */
+.topbar, .sidebar, .content, .page-card, .toc-box,
+.search-dropdown, .backlinks li a, .stat-card, .quick-link,
+.file-drop, .add-form input, .add-form button,
+.config-card, .badge, .page-type-badge, .page-body table,
+.page-body blockquote, .page-body pre {
+    border-radius: 0;
+}
+
 body {
     font-family: "Noto Sans KR", -apple-system, BlinkMacSystemFont, "Malgun Gothic", sans-serif;
     color: var(--text);
@@ -137,6 +145,10 @@ a:hover {
     text-decoration: none;
 }
 
+.search-dropdown a.selected {
+    background: var(--accent-light);
+}
+
 .search-dropdown .search-highlight {
     color: var(--namu-green);
     font-weight: 600;
@@ -527,6 +539,16 @@ a:hover {
     margin-bottom: 28px;
 }
 
+.empty-state {
+    grid-column: 1 / -1;
+    padding: 32px;
+    text-align: center;
+    color: var(--text-muted);
+    font-size: 14px;
+    border: 2px dashed var(--border);
+    margin: 8px 0;
+}
+
 .page-card {
     display: block;
     padding: 10px 14px;
@@ -946,11 +968,49 @@ h4 .headerlink {
     background: var(--namu-green);
 }
 
+/* Hamburger menu button */
+.topbar-menu-btn {
+    display: none;
+    background: none;
+    border: none;
+    color: white;
+    font-size: 22px;
+    cursor: pointer;
+    padding: 0 8px;
+}
+
+/* Sidebar overlay */
+.sidebar-overlay {
+    display: none;
+}
+
 /* Responsive */
 @media (max-width: 768px) {
+    .topbar-menu-btn { display: flex; align-items: center; }
+
     .sidebar {
+        position: fixed;
+        left: -260px;
+        top: 46px;
+        bottom: 0;
+        width: 260px;
+        z-index: 99;
+        transition: left 0.25s ease;
+        background: var(--bg);
+        display: block !important;
+    }
+    .sidebar.open { left: 0; }
+
+    .sidebar-overlay {
         display: none;
+        position: fixed;
+        inset: 0;
+        top: 46px;
+        background: rgba(0,0,0,0.4);
+        z-index: 98;
     }
+    .sidebar-overlay.active { display: block; }
+
     .content {
         margin-left: 0;
         padding: 16px 14px;
@@ -958,4 +1018,27 @@ h4 .headerlink {
     .topbar-search {
         max-width: 180px;
     }
+}
+
+/* Dark mode */
+@media (prefers-color-scheme: dark) {
+    :root {
+        --bg: #1a1a2e;
+        --bg-alt: #16213e;
+        --bg-hover: #0f3460;
+        --text: #e0e0e0;
+        --text-muted: #8e8e8e;
+        --text-dark: #ffffff;
+        --border: #2a2a4a;
+        --accent-light: #1a3a3a;
+        --namu-green: #00b4a6;
+        --namu-green-dark: #008c7e;
+    }
+
+    .topbar { background: #004d40; }
+    .page-body h2 { background: #006050; }
+    .page-card { background: var(--bg-alt); }
+    .toc-box { background: var(--bg-alt); }
+    .sidebar { background: var(--bg); border-right-color: var(--border); }
+    img { opacity: 0.9; }
 }