開發自己的 Plugin

list-table/                   plugin 原始資料夾（你在這裡開發）
├── notecraft-plugin.json
├── schema.json
└── renderer.tsx

my-notes/                     專案根，在這裡執行指令
├── .notecraft/
│   ├── plugins.json          安裝時 --apply 寫入
│   └── plugins/
│       ├── _types.d.ts       安裝時產生
│       └── list-table/       安裝時複製過來
└── notes/                    筆記資料夾
    └── reading/
        ├── 2026.mdx
        └── books.list.json

{
  "$schema": "https://raw.githubusercontent.com/SteveLin100132/notecraft/main/plugins/notecraft-plugin.schema.json",
  "id": "list-table",
  "title": "清單表格",
  "description": "把 JSON 清單畫成表格",
  "version": "0.1.0",
  "dataSchema": "schema.json",
  "engines": { "notecraftapp": ">=1.6.0" }
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "清單表格資料檔",
  "type": "object",
  "required": ["columns", "items"],
  "properties": {
    "meta": {
      "type": "object",
      "properties": {
        "title": { "type": "string" },
        "description": { "type": "string" },
        "backTo": { "type": "string" }
      }
    },
    "columns": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["key", "label"],
        "properties": {
          "key": { "type": "string" },
          "label": { "type": "string" }
        }
      }
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": { "type": ["string", "number", "boolean", "null"] }
      }
    }
  }
}

{
  "meta": {
    "title": "2026 書單",
    "description": "今年讀過與想讀的書",
    "backTo": "/notes/reading/2026"
  },
  "columns": [
    { "key": "title", "label": "書名" },
    { "key": "author", "label": "作者" },
    { "key": "status", "label": "狀態" }
  ],
  "items": [
    { "title": "原子習慣", "author": "James Clear", "status": "讀完" },
    { "title": "深度工作力", "author": "Cal Newport", "status": "讀完" },
    { "title": "設計的心理學", "author": "Don Norman", "status": "閱讀中" },
    { "title": "人月神話", "author": "Frederick Brooks", "status": "想讀" }
  ]
}

import type { PluginRendererProps } from "@notes/plugins/_types";

interface Column {
  key: string;
  label: string;
}

interface ListData {
  meta?: { title?: string; description?: string };
  columns: Column[];
  items: Record<string, string | number | boolean | null>[];
}

// 以字串注入 <style>：不可含 < > & " ' 這五個字元
const CSS = `
.lt-root { padding: 16px; font-size: 14px; color: var(--text-body); }
.lt-root table { width: 100%; border-collapse: collapse; }
.lt-root th, .lt-root td { padding: 6px 10px; border-bottom: 1px solid var(--border-subtle); text-align: left; }
.lt-root th { color: var(--text-muted); font-weight: 600; }
.lt-root .lt-more { margin-top: 8px; font-size: 12px; color: var(--text-muted); }
`;

export default function ListTable({ data, options, mode }: PluginRendererProps<ListData>) {
  const limit = typeof options.limit === "number" ? options.limit : data.items.length;
  const rows = data.items.slice(0, limit);
  const hidden = data.items.length - rows.length;

  return (
    <div className="lt-root">
      <style>{CSS}</style>
      <table>
        <thead>
          <tr>
            {data.columns.map((c) => (
              <th key={c.key}>{c.label}</th>
            ))}
          </tr>
        </thead>
        <tbody>
          {rows.map((item, i) => (
            <tr key={i}>
              {data.columns.map((c) => (
                <td key={c.key}>{String(item[c.key] ?? "")}</td>
              ))}
            </tr>
          ))}
        </tbody>
      </table>
      {mode === "embed" && hidden > 0 && <p className="lt-more">還有 {hidden} 筆，開啟完整檢視頁查看。</p>}
    </div>
  );
}

npx notecraftapp install-plugin ../list-table --apply "**/*.list.json"

[notecraftapp] ✓ 已安裝 list-table v0.1.0 → .notecraft/plugins/list-table/
[notecraftapp] ✓ 已在 .notecraft/plugins.json 加入映射：**/*.list.json

{
  "plugins": [
    {
      "plugin": "list-table",
      "files": [
        "**/*.list.json"
      ]
    }
  ]
}

npx notecraftapp build ./notes

import PluginView from "@/components/PluginView.astro";

今年的書單前兩本：

<PluginView src="reading/books.list.json" options={{ limit: 2 }} caption="書單前兩本" />

npx notecraftapp install-plugin ../list-table --force