Markdown 擴充語法示範

NoteCraft 在標準 Markdown / MDX 之外，提供三種類 Material for MkDocs 的內容增強語法，皆以 remark-directive 於 build 階段渲染、樣式遵循 trendlink-design，正式環境同樣可用。

Admonitions（提示框）

用 :::類型 容器標記，支援 note / info / tip / success / warning / danger。

Content tabs（內容分頁）

用 ::::tabs 包住多個 :::tab{label="…"}；切換以框架無關的 vanilla JS 實作，停用 JS 時會展開所有面板、不遺失內容。

巢狀容器規則：外層 tabs 要比內層 tab 多一個冒號（::::tabs 包 :::tab），remark-directive 才能正確區分巢狀層級。

npm install notecraft

pnpm add notecraft

yarn add notecraft

Tooltips（行內提示）

用 :tip[可見文字]{content="說明"} 標記，滑鼠移上或鍵盤聚焦即顯示：像 OAuth一種授權框架，讓第三方應用在不取得密碼的情況下存取資源。 這樣。

Badge（行內標籤）

用 :badge[文字]{variant outline size icon href} 行內 directive 標記。variant 與 Admonitions 共用同一套語意色（note / info / tip / success / warning / danger / neutral）。

• 預設 solid：新 Beta 必填 v1.8.0
• 加 outline 旗標：note info neutral
• 帶 icon：新功能 已完成 警告
• size="sm"（適合表格 cell 內）：必填 選用
• 可點擊（有 href）：查看 Admonitions GitHub

Steps（步驟）

用 ::::steps{layout} 容器包多個 :::step{title status}，預設 vertical。status 三態：done / current / todo（預設 todo）。

Vertical（預設）

1. 安裝依賴

   執行 npm install，等待依賴下載完成。

2. 02

   設定環境變數

   複製 .env.example 為 .env，填入 必填 欄位。

3. 03

   啟動 Dev Server

   npm run dev 後開啟 http://localhost:4321。

Horizontal

layout="horizontal"；視窗 < 640px 時自動降級為 vertical（內建、作者無法關閉）。

1. 計劃

   釐清需求與待釐清項。

2. 設計

   產出規格與 task。

3. 03

   實作

   依 task 撰寫元件與樣式。

4. 04

   驗收

   跑 astro build 確認通過。

自訂起始序號

3. 03

   第三步

   從 03 開始計數。

4. 04

   第四步

   接著是 04。

程式碼區塊增強（Code blocks）

圍欄程式碼於 build 階段渲染為白底程式碼塊：語言標籤、複製按鈕、固定行號欄、整行高亮與可展開的程式碼註解。

行號 + 整行高亮

每個程式碼塊都有固定行號欄；在 fence 的語言後加 {行號}（如 {3,6-7}、1-indexed）即可標出重點行：

export function signIn(user: string, token: string) {
  if (!token) {
    throw new Error("missing token"); // 第 3 行被 highlight
  }
  const session = createSession(user);
  session.token = token; // 第 6–7 行被 highlight
  return session;
}

檔名標題

加上 title="路徑/檔名" 會在標題列的語言標籤旁顯示檔名（可與 {行號} 並用）：

import { createSession } from "./session";
const token = readToken(); // 第 2 行被 highlight
export const session = createSession(token);

Code annotations（可展開註解）

用 :::annotate 容器包住「程式碼 + 編號清單」，程式碼中以 (n)! 標記，點擊標記即浮現對應說明（停用 JS 時清單依序顯示、不遺失內容）：

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