3.1 撰寫筆記
Markdown 與 MDX
筆記資料夾裡的 .md 與 .mdx 都會被讀取。這頁說明兩者能寫的東西差在哪、MDX 容易踩到的語法，以及什麼時候該改副檔名。
筆記資料夾底下所有 .md 與 .mdx 檔都會被讀成筆記，可以混著放。frontmatter、網址規則、圖片、相對連結、程式碼區塊與提示框等擴充語法，兩種格式都一樣。
在 view 模式用介面「新增筆記」建立的檔案一律是 .mdx。
差在哪裡
MDX 是「Markdown 加上 JSX」：可以 import 元件、在內文放 <元件 />。代價是語法比較嚴格。
.md | .mdx | |
|---|---|---|
import 與 JSX 元件 | 不行 | 可以 |
@ai-visualize 標記 | 不會被處理，標記文字會直接顯示；不計入待生成，view／build 時印出提示 | 可以 |
<PluginView> 內嵌資料檔 | 不行 | 可以 |
HTML 註解 <!-- … --> | 可以，不會顯示 | 語法錯誤，改用 {/* … */} |
| 原始 HTML | 照 HTML 規則 | 當成 JSX，標籤必須閉合，例如 <br /> |
| 縮排四格的程式碼 | 變成程式碼區塊 | 只是一般段落，要用 ``` 圍欄 |
文字裡的 {、< | 一般字元 | 有特殊意義，見下一節 |
@ai-visualize 標記的寫法見標記語法，<PluginView> 見在筆記裡嵌元件。
MDX 常見陷阱
這些字元放在程式碼區塊或行內 code 裡都不受影響，只有寫在一般文字裡才要注意。
下圖把同一段原文分別當成 .md 與 .mdx 渲染。上方按鈕是下面幾節提到的寫法，原文也可以自己改改看。
設定寫成 {a: 1}。
這篇筆記打不開
第 1 行第 8 欄：Could not parse expression with acorn
大括號 { }
{ 會開始一段 JavaScript 運算式。
{a: 1}這類寫法無法解析，筆記會編譯失敗{name}能解析，但渲染時找不到name這個變數，一樣失敗
要顯示大括號本身，前面加反斜線，或放進行內 code：
設定寫成 \{ "debug": true \}，或寫成 `{ "debug": true }`。角括號 <
< 後面接英文字母會被當成 JSX 標籤的開頭，接數字（例如 <3）則是語法錯誤。a < b 這種後面有空白的寫法沒問題。
要顯示 < 本身，寫成 \< 或 <。
<https://example.com> 這種角括號網址在 MDX 也會出錯。直接寫網址，或寫成 [文字](https://example.com)。
註解
<!-- 這行在 MDX 會報錯 -->
{/* 這樣才對，內容不會顯示 */}自訂標題 id
## 標題 {#my-id} 的 {#my-id} 會被當成運算式而失敗。NoteCraftApp 不支援自訂錨點，id 一律自動產生，規則見標題、目錄與錨點。
什麼時候改成 .mdx
只在需要下面其中一樣時才改：
- 加
@ai-visualize標記，讓 AI 生成圖表 - 用
<PluginView>把資料檔嵌進內文 - import 其他元件
純文字的筆記留在 .md 就好，不必擔心 {、< 這些字元。
改之前，先在檔案裡找這幾樣，照上一節改掉：
<!--開頭的 HTML 註解- 一般文字裡的
{、}、< <https://…>形式的網址- 沒閉合的 HTML 標籤，例如
<br> - 縮排四格的程式碼
改副檔名對網址的影響
網址取自去掉副檔名的路徑，guides/cache.md 改成 guides/cache.mdx 後網址仍是 /notes/guides/cache。
series.json的slugs本來就不含副檔名，不用改- 以網址識別的閱讀進度、頁籤不受影響
- 其他筆記裡寫
./cache.md的相對連結仍會導到同一個網址，但在 GitHub、VS Code 裡點下去會找不到檔案，順手改成./cache.mdx
不要讓同名的 cache.md 與 cache.mdx 放在同一個資料夾：兩者會對到同一個網址。網址的完整規則見巢狀資料夾與網址。