程式碼區塊

程式碼塊在 build 階段就渲染成靜態 HTML，.md 與 .mdx 寫法相同。

基本寫法

用三個反引號圍起來，後面接語言名稱。下圖的「原文」框可以直接改，「筆記頁」框是 NoteCraftApp 筆記頁實際渲染出來的樣子，會跟著重算；上方的按鈕切換幾組現成的例子。這頁之後的圖都是同一種操作方式。

export const ttl = 60;

每個程式碼塊都有：

• 標題列：左邊是語言標籤（語言名稱轉大寫，例如 TS；沒寫語言時顯示 TEXT），右邊是複製鈕
• 行號欄：固定顯示，沒有關閉的選項
• 長的行不會自動換行，程式碼區可以橫向捲動

複製鈕

按下後複製整段原始碼，按鈕顯示「已複製」約 1.6 秒。下方程式碼註解的 (1)! 標記不會被複製進去。

用 --host 0.0.0.0 讓區網其他電腦以 http://<IP> 連進來時，瀏覽器不提供剪貼簿 API，複製鈕會改用舊的複製方式，一般瀏覽器照樣能複製。真的複製不了時，按鈕顯示「無法複製」並把整段程式碼選取起來，再自己按複製鍵（macOS 是 ⌘C）即可。

檔名與整行高亮

語言後面可以再加兩種設定，可以並用：

import { createSession } from "./session";
const token = readToken();
export const session = createSession(token);

上色規則

NoteCraftApp 不使用 Shiki 這類依語言切換的高亮器，而是用一套內建的規則替所有語言上色。語言名稱只影響標籤文字，任何名稱都能寫；也沒有可以切換的配色主題。

因此 JavaScript、TypeScript、JSX、JSON 的效果最完整。其他語言只有字串、數字、函式呼叫這些共通的部分會上色：

• # 開頭的註解（Python、Bash、YAML）與 -- 開頭的註解（SQL）不會顯示成註解色
• 跨行的 /* … */ 與跨行字串，只有逐行能配對的部分會上色

// 讀取設定，沒有就用預設值
interface Options { ttl?: number }
export async function load(path: string): Promise<Options> {
  const raw = await readFile(path, "utf8");
  return { ttl: 0x3c, ...JSON.parse(raw) };
}

```mermaid 這類圍欄只會顯示成一般程式碼，不會畫成圖。要畫圖請用 @ai-visualize 標記。

行內 code

用一對反引號：`Cache-Control`。行內 code 以等寬字、淺灰底顯示，不上色。

在 .mdx 裡，{、< 放在行內 code 或程式碼塊裡都不用跳脫，見 Markdown 與 MDX。另外 .md 裡縮排四格的程式碼也會變成程式碼塊（標籤是 TEXT），.mdx 不會。

程式碼註解

用 :::annotate 包住「一個程式碼塊＋一個編號清單」，在程式碼裡寫 (1)!、(2)! 當標記。讀者點標記，就會浮出清單裡對應的那一項：

function handler(req: Request) { // 1
  validate(req);
  return ok(req); // 2
}

• (n)! 對應清單的第 n 項
• 再點一次標記、點別處或按 Esc 關閉說明
• 標記數和清單項數不同時，build log 會出現警告
• 容器裡少了程式碼塊或編號清單，會退回一般區塊顯示，同樣在 build log 警告

提示框與分頁

下面這些語法在 .md 與 .mdx 都能用。名稱打錯的 :::xxx 會原樣顯示成文字。

提示框

• 自訂標題：:::warning{title="升級前"} 或 :::warning[升級前]
• 可收合：:::tip{collapsible} 預設收起，:::tip{collapsible open} 預設展開

分頁

外層 tabs 要比內層 tab 多一個冒號：

npm install -g notecraftapp

pnpm add -g notecraftapp

label 沒寫時，分頁會被命名為「分頁 1」「分頁 2」……，並在 build log 警告。分頁按鈕取得焦點時，可以用 ← →、Home、End 鍵切換。

其他

:badge 的 icon 可用 sparkle、check、star、bolt、flag、info、warning、danger、note、success。和分頁一樣，steps 的冒號要比 step 多一個。