6.5 參考

ignore.json

ignore.json 的讀取位置、欄位、規則語法、內建排除，以及格式錯誤與各種提醒的處理方式。

本頁目錄

設定方式與範例見排除檔案，這頁只列規格。1.10.0 起支援。

讀取位置

只讀一個位置：<執行指令的目錄>/.notecraft/ignore.json，和 plugins.json 同一處。

執行方式	讀取的檔案
在 `my-project/` 執行 `npx notecraftapp view ./docs`	`my-project/.notecraft/ignore.json`
在 `docs/` 執行 `npx notecraftapp view`	`docs/.notecraft/ignore.json`

不會合併兩份。執行目錄和筆記資料夾不同、而筆記資料夾裡也有 .notecraft/ignore.json 時，build log 會提醒那一份不會生效。

檔案不存在時只套用內建排除，不印任何訊息。

欄位	型別	必填	說明
`ignore`	字串陣列	否	規則清單，省略等同空陣列
`$schema`	字串	否	給編輯器用，app 不讀。網址 `https://cdn.jsdelivr.net/npm/notecraftapp/schemas/ignore.schema.json`

頂層必須是物件，寫成陣列 [...] 會讓 build 失敗。其他欄位會被略過，build log 印警告（常見是把 ignore 拼成 ignores）。

與 .gitignore 相同。路徑一律相對筆記資料夾、以 / 分隔，Windows 也一樣。

寫法	比對
`name`	不含 `/`：任何深度的同名檔案或資料夾
`/name`	開頭 `/`：只比對筆記資料夾根目錄
`a/b`	中間有 `/`：從筆記資料夾的根算起
`dir/`	結尾 `/`：只比對資料夾，整個子樹排除
`*`、`?`、`[abc]`	不跨 `/` 的萬用字元
`**`	跨任意層
`!pattern`	把前面排除的收回；多條規則命中同一個檔案時，最後一條決定結果
`#…`	註解；要比對 `#` 開頭的檔名寫 `\#`
空字串、只有空白	略過

資料夾整個被排除時不會往下讀，所以裡面的檔案無法用 ! 收回。

不必寫，也無法用 ! 解除：

對象	被排除時
`.md`／`.mdx`	不是筆記：沒有頁面，不在 Sidebar、筆記列表、搜尋、儀表板
資料檔 `.json`	不交給 Plugin；`plugins.json` 的 `files`、`exclude` 比對之前就略過
圖片與附件	不複製進 build 產物；`view` 的 `/notes-assets/*` 回 404
`view` 的寫入 API	標籤統計、改名、刪除不碰它；以 slug 找筆記時當作不存在；資料夾選單不列；不能在被排除的位置新增筆記
`serve`	改了不觸發 rebuild；被排除的資料夾不監看
`build` 快取	改了不讓快取失效，也不計入筆記數
`note-scanner` subagent	掃描 `@ai-visualize` 標記時略過

情況	結果
不是合法 JSON、頂層不是物件、`ignore` 不是字串陣列	build 失敗，指出檔案與第幾個元素
規則裡的 `[` 沒有對應的 `]`	build 失敗，指出第幾條
有不認得的頂層欄位	警告
想用 `!` 解除內建排除（例如 `!dist/`）	警告，規則不生效
`!` 規則的目標在一個整個被排除的資料夾裡	警告，提示改寫成 `資料夾/*`
筆記連到被排除的筆記	警告，連結照樣產生，但會是 404
筆記引用被排除的圖片	警告，圖片不會出現在產物
系列章節或 `<PluginView src>` 指到被排除的檔案	系列跳過這一章並警告；`<PluginView>` 照原本規則 build 失敗，訊息說明是被排除
某條規則一個檔案都沒命中	不提醒

build 完會再檢查一次產物，出現被排除的檔案就讓 build 失敗。