NoteCraftApp 是一款為寫技術筆記的人打造的筆記工作台。它直接讀你專案裡的 md／mdx 資料夾，提供資料夾樹、四種筆記檢視、系列閱讀進度、⌘K 全站搜尋與多筆記頁籤；在 MDX 裡用 @ai-visualize 標記描述想要的圖，Claude Code 就會生成 React 互動元件並寫回筆記。同一份筆記還能一鍵轉成簡報，結構化的 JSON 資料檔（ER 圖、OpenAPI 文件）則交給可安裝的 plugin 渲染。寫筆記、補圖表、轉簡報，都在同一本筆記裡完成。
完整說明請看 使用文件：安裝、設定、各項功能的用法與 CLI 參考都在那裡。
功能
- 工作台 — Rail＋檔案樹 Sidebar＋主區三欄；筆記列表有 List／Board／Table／Timeline 四種 view 與 Drawer 預覽，
⌘K 跨頁跳轉。→ 工作台
- 儀表板與更新月曆 — 閱讀狀態、AI 待生成、寫作頻率、系列進度、標籤分布、更新日誌。→ 儀表板
- AI 視覺化 — 在 MDX 用
@ai-visualize 描述想要的圖，Claude Code 生成 React 互動元件並寫回筆記；驗證沒過不寫回。→ AI 視覺化
- 放大檢視 — 寬元件搬進可平移縮放的全螢幕畫布，互動完整保留，可匯出 PNG。→ 放大檢視
- 筆記轉簡報 — 一篇筆記變成 16:9 多頁簡報，筆記裡的互動元件原樣搬進投影片。→ 筆記轉簡報
- 系列與頁籤 — 多篇筆記串成有順序的閱讀路徑；開過的筆記留下頁籤，切回來停在上次讀到的位置。→ 系列
- Plugin — ER 圖、OpenAPI 這類結構化 JSON 交給可安裝的渲染器畫成頁面。→ Plugin
- 零鎖定 — 讀的是你現有的資料夾，產出是純靜態網站，生成的元件是 repo 裡的原始碼。
操作說明
01 更新月曆 — 每篇筆記，落在它更新的那一天
筆記依最後更新日排進日期格，色塊就是閱讀狀態；月檢視看整體節奏，週檢視看這幾天寫了什麼。→ 儀表板
02 儀表板 — 寫了多少、讀到哪，打開就知道
筆記總數與閱讀狀態、AI 待生成、寫作頻率、最近更新、系列進度、標籤分布、更新日誌，集中在同一頁。→ 儀表板
03 新增筆記 — 新增、標記、刪除，不必離開瀏覽器
view 模式下右上角會出現「+ 新增筆記」：自動產生 slug 並套用 frontmatter 模板，標籤用 chip 輸入並自動完成。→ 在工作台編輯
04 筆記頁籤 — 切回來，停在上次讀到的地方
開過的筆記與資料檔都留在最上方，可固定、拖曳、右鍵管理；右側「全部頁籤」能篩選，也能重開剛關閉的。→ 頁籤
05 Board view — 拖曳卡片，就改了閱讀狀態
依未開始、閱讀中、已完成分成三欄，把卡片拖到另一欄，筆記的狀態就跟著更新。→ 筆記列表
06 Drawer 預覽 — 單擊先預覽，確定了再打開
單擊一列就在右側看到摘要、Metadata、@ai-visualize 標記與同系列章節；雙擊或點列尾箭頭才進入筆記。→ 筆記列表
07 List view — 四種分組，⌘K 隨時跳轉
依資料夾、系列、標籤、月份分組，篩選條件都寫在網址參數，分享連結就是同一個畫面。→ ⌘K 搜尋
08 Plugin 管理 — ER 圖、API 文件，交給 Plugin 渲染
列出已安裝的外掛、映射規則與命中的資料檔；dev 環境下可以一鍵啟用或停用。→ Plugin
09 系列 — 一份 series.json，串成閱讀路徑
在 .notecraft/series.json 定義系列（選用），多篇筆記依章節排成有順序的閱讀路徑，進度一目了然。→ 系列
Quick Start
在你的 md／mdx 資料夾所在專案下：
# 開啟工作台（HMR＋可寫入）
npx notecraftapp view ./docs
# 要用 AI 視覺化與筆記轉簡報：把 skill 與 subagent 裝進專案的 .claude/
npx notecraftapp init-skill
# 要渲染 ER 圖或 OpenAPI 文件：從官方 store 裝 plugin
npx notecraftapp install-plugin
首次執行會複製套件到 ~/.notecraft/app-<version>/ 並跑一次 npm install（約 30 秒），之後每次啟動秒開。
五個子命令與全部參數見 CLI 參考。
排除檔案
筆記資料夾裡有不想讓 NoteCraft 讀的東西（草稿、私人筆記、測試用的大 JSON），在 .notecraft/ignore.json 寫規則，語法同 .gitignore：
{
"$schema": "https://cdn.jsdelivr.net/npm/notecraftapp/schemas/ignore.schema.json",
"ignore": [
"drafts/",
"**/*.private.md",
"CHANGELOG.md",
"archive/*",
"!archive/keep-this.mdx"
]
}
| 寫法 | 意義 |
|---|
CHANGELOG.md | 不含 /：任何深度的同名檔或資料夾 |
/README.md | 開頭 /：只比對筆記資料夾根目錄 |
drafts/ | 結尾 /：只比對資料夾，整棵子樹排除 |
*.test.mdx、**/tmp/ | *、?、[abc] 不跨層，** 跨任意層 |
!archive/keep-this.mdx | 把先前排除的納回，後寫的勝 |
# 說明 | 註解 |
- 路徑相對筆記資料夾；
ignore.json 與 plugins.json 放在同一個 .notecraft/（執行 npx notecraftapp 的資料夾）
- 被排除的檔完全不讀：不成為筆記、不被 plugin 認領、不出現在資料夾樹與新增筆記的選單、圖片不複製進產物、改了也不觸發 rebuild
. 開頭的檔案與資料夾、node_modules/、dist/ 一律排除，不必寫，也無法用 ! 解除- 資料夾整個被排除後，裡面的檔用
! 救不回（同 git）：要保留 archive/ 裡的一篇，寫 archive/* 而不是 archive/
- 改了
ignore.json 會自動生效（view 重啟 dev server、serve 重新 build）；格式寫錯會讓 build 失敗並指出哪一條
- 它不是存取控制：被排除的檔仍在硬碟上、仍會被 git commit；它保證的是 build 產物（
dist/）裡沒有它們
系統需求
- Node.js ≥ 22
- macOS／Linux／Windows（Windows 11 已驗證
view、build、serve、init-skill、install-plugin）
- AI 視覺化與筆記轉簡報另需 Claude Code
開發者
想改 CLI 本身或 UI，見 參與開發、CLAUDE.md 與 CHANGELOG.md。
License
MIT — 見 LICENSE
