定義與引用

寫系統文件時，常在好幾篇筆記重複寫同一段說明，例如「管理員負責什麼」。之後要改，就得同時改好幾處。

定義與引用讓這段內容只存在一個地方：

.md 與 .mdx 都能用。引用只寫 id，不寫文件路徑：來源筆記搬到別的資料夾或改檔名，引用都不會斷。

下圖的「原文」框有兩篇筆記，用上方的檔案頁籤切換，可以直接改；「筆記頁」框是 NoteCraftApp 實際渲染出來的樣子，也能切換要看哪一篇。滑過淡底色的行內引用會出現預覽卡，點「前往來源」或「被 N 篇引用」會切到對應的那篇。

寫一段定義

::::define{id="hr.role-admin"}
**管理員**：負責帳號審核、權限設定與稽核報表。

:::note
離職時要同步撤權。
:::
::::

• define 是容器，裡面放什麼都可以：段落、清單、表格、程式碼區塊、圖片，以及提示框、:tip、分頁、步驟等擴充語法
• 裡面還有別的容器（例如 :::note）時，外層的冒號要比內層多，上例外層用四個
• 只能放在筆記的最上層，不能放進提示框或分頁裡

id 的規則

• 整個筆記資料夾內不能重複
• 可以用中文、英文、數字、_、-，以 . 分段。習慣上第一段當分類，例如 hr.role-admin、crm.role-admin
• 要寫成 id="…"。{#hr.role-admin} 這種簡寫遇到 . 會被當成 class，id 只剩 hr

顯示名稱

預覽卡、反向連結、指令面板會顯示定義的名稱，依序取：

1. label 屬性：::::define{id="hr.leave-status" label="假單狀態"}
2. 內容裡第一個粗體的文字（上例是「管理員」）
3. id

嵌入：include

## 簽核角色

::include{id="hr.role-manager"}

嵌入的內容和來源走同一套渲染，提示框、表格、分頁都長得一樣。左側有一條細線，上方標著「嵌入自」與來源筆記的標題，右邊的「前往來源」會打開來源筆記、捲到那段定義並短暫標示。

• 定義裡的標題會配合嵌入的位置調整層級：最高的一級變成「嵌入處前一個標題的下一級」，最多到 h4
• 嵌入的標題會進目錄，前面多一個嵌入的圖示
• 嵌入的內容不會被全文搜尋索引，搜尋只會找到來源那一篇

定義裡有元件時

定義裡可以放 AI 生成的元件（GeneratedFrame）或其他 JSX 元件，來源筆記照常顯示。但元件的 import 屬於來源檔，所以嵌入處與預覽卡不會渲染元件，改顯示「此處有互動元件，請至原文檢視」。

import 要寫在檔案開頭，不能寫在定義裡，否則 build 會失敗。

行內引用：:ref

送出後由 :ref[主管]{id="hr.role-manager"} 在兩個工作天內簽核。
逾期時通知 :ref{id="hr.role-admin"}。

省略 [文字] 時顯示定義的名稱。行內引用的樣式是淡色底加實線底線，和一般連結（藍字）、:tip（虛線）分得開。

內容太長時，卡片先顯示前段，按「看完整內容」展開。

誰引用了這段定義

改定義之前，可以先看哪些筆記會受影響：

• 每段定義上方有「被 N 篇引用」，點開列出引用的筆記，以及是嵌入還是行內引用
• 被引用的筆記，頁首有「被引用 N」按鈕，打開後是整篇的反向連結，可以依定義篩選
• 筆記列表點一篇筆記，右側預覽會列出「被引用」「本篇定義」「引用的定義」
• 指令面板（⌘K）輸入 id 的任一段或定義名稱，可以直接跳到定義所在處

在開發模式下刪除一篇筆記時，如果它的定義被別篇引用，確認對話框會列出那些筆記。刪除不會被擋下，但之後 build 會失敗，要改掉那些引用（或用 git 復原）。

會讓 build 失敗的寫法

錯誤訊息會指出檔案與行號；npm run dev 時直接顯示在瀏覽器上。