6.4 參考
series.json
series.json 的完整欄位定義、讀取位置與優先序，以及 slugs 的寫法與容錯規則。
設定方式與範例見系列設定，這頁只列規格。
讀取位置
依序找下面兩個位置，用第一個存在且格式正確的：
<筆記資料夾>/.notecraft/series.json<執行指令的目錄>/.notecraft/series.json
兩份不會合併。第一份格式不對時，build log 會印警告，接著改讀第二份；兩份都沒有或都不對，視為沒有系列。
頂層
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
series | 物件陣列 | 是 | 系列清單，順序即顯示順序 |
$schema | 字串 | 否 | 給編輯器用，app 不讀 |
每個系列
七個欄位都必填，缺一個整份檔案都視為格式不正確。
| 欄位 | 型別 | 可選值 | 說明 |
|---|---|---|---|
id | 字串 | — | 識別碼，出現在網址 ?series= |
title | 字串 | — | 系列名稱 |
eyebrow | 字串 | — | 系列卡片上方的小字 |
description | 字串 | — | 一句話說明 |
accent | 字串 | "blue"、"orange"、"navy" | 強調色 |
icon | 字串 | "target"、"code"、"layers"、"bookOpen"、"bolt" | 圖示 |
slugs | 字串陣列 | — | 章節清單，順序即章節順序 |
slugs 的寫法
| 章節類型 | 寫法 | 例子 |
|---|---|---|
| 筆記 | 相對筆記資料夾的路徑，去掉副檔名 | guides/oauth/flow |
| 資料檔頁 | view: 加相對路徑，去掉 .json | view:api/orders.openapi |
讀取時會先整理每一項，所以下面幾種寫法都指向同一篇：
- 開頭的
./會去掉：./guides/oauth/flow - 多餘的
/會合併或去掉 - 筆記的
.md／.mdx、資料檔的.json會去掉：guides/oauth/flow.mdx、view:api/orders.openapi.json
view: 前綴要保留。閱讀進度以這個字串記錄，筆記 a/b 與資料檔 view:a/b 是兩個不同的章節。
對不到時
這些情況只在 build log 印警告，不會讓 build 失敗：
| 情況 | 結果 |
|---|---|
| 筆記 slug 找不到對應筆記 | 跳過這一章 |
view: 找不到對應的資料檔 | 跳過這一章；請確認 plugins.json 的 files 有涵蓋它 |
| 資料檔存在，但負責它的 plugin 已停用 | 跳過這一章 |
| 同一個 slug 出現在兩個系列 | 以先出現的系列為準 |