Acard 플러그인 만들기

한눈에 보기

5분 시작

SDK(acard-plugin-sdk)와 템플릿 세 개(블록 · 명령 · CSS)는 Acard 저장소의 packages/ 에 있어요. 공개 템플릿 저장소는 준비 중이에요. 아래는 packages/ 가 보이는 폴더에서 시작해요. CLI 는 아직 npm 에 올리지 않아서 SDK 파일을 bun 으로 바로 실행해요(Bun 1.1 이상).

cp -r packages/acard-plugin-template-block my-plugin
alias acard-plugin="bun $PWD/packages/acard-plugin-sdk/bin/acard-plugin.js"
cd my-plugin
bun run build               # src/main.js -> main.js (의존성 없음)
acard-plugin validate       # 마지막 줄 ACARD_PLUGIN_OK <id> <version>
acard-plugin dev            # http://127.0.0.1:4870/ 미리보기, 저장하면 다시 그려요 (--port N)
acard-plugin pack           # <id>-<version>.zip (manifest.json · main.js · styles.css 만)

acard-plugin dev 는 Acard 와 같은 구조(다른 origin 의 sandbox="allow-scripts" 프레임, 같은 CSP)로 블록을 미리 보여 줘요. 명령과 사이드 패널은 zip 으로 내 Acard 에 설치해서 확인해요.

만든 zip 은 설정 > 플러그인 의 zip 칸에 끌어 놓으면 권한 동의 화면이 나오고, 허락하면 설치돼요. 직접 설치한 플러그인에는 "검토되지 않음" 표시가 붙어요.

manifest.json

템플릿의 manifest 를 그대로 보여 드려요. id·name·author·description 만 바꾸면 돼요.

{
  "id": "calc-tip",
  "name": "Tip Calculator",
  "version": "1.0.0",
  "minAppVersion": "1",
  "description": "Splits a bill with a tip: move the sliders and the result updates.",
  "author": "Your Name",
  "license": "MIT",
  "permissions": [
    "storage"
  ],
  "contributes": {
    "blocks": [
      {
        "id": "tip",
        "name": "팁 계산기",
        "icon": "%",
        "description": "금액·팁·인원을 바꾸면 1인당 금액을 바로 계산해요."
      }
    ]
  },
  "settings": [
    {
      "key": "currency",
      "type": "select",
      "label": "통화",
      "default": "KRW",
      "options": [
        {
          "value": "KRW",
          "label": "원 (KRW)"
        },
        {
          "value": "USD",
          "label": "달러 (USD)"
        },
        {
          "value": "EUR",
          "label": "유로 (EUR)"
        },
        {
          "value": "JPY",
          "label": "엔 (JPY)"
        }
      ]
    }
  ]
}

• id: 영문 소문자로 시작, 2-40자, acard 를 넣거나 -plugin 으로 끝나면 안 돼요.
• version: x.y.z. GitHub 로 낼 때는 릴리스 태그가 이 값(또는 v 를 붙인 값)과 같아야 해요.
• contributes: blocks(10개까지) · commands(20개까지) · panel({name, icon} 하나) · css: true 중 하나 이상. 블록·명령·패널이 있으면 main.js 가 있어야 해요.
• settings(30개까지): toggle · text · textarea · number · slider · select · color. 사용자가 설정 화면에서 바꾼 값이 ctx.settings 로 와요.
• 크기: manifest 16 KB, main.js 256 KB, styles.css 64 KB, zip 1 MB(압축을 푼 합계 2 MB). zip 에는 이 세 파일만, 맨 위나 폴더 하나 안에 넣어요.

권한

어떤 권한으로도 로그인 정보, 쿠키, 다른 페이지, 다른 작업 공간, Acard 화면 자체에는 닿지 못해요.

UI 컴포넌트와 다시 계산하기

플러그인은 HTML 을 보내지 않고 정해진 노드로 된 트리를 돌려줘요. 그래서 모든 플러그인이 Acard 와 같은 모양(글꼴·색·간격·다크 모드)으로 보여요. 컨트롤(슬라이더·입력·선택·토글)이 바뀌면 onAction(ctx, { name: "change", values }) 다음 render(ctx) 가 다시 불려서 결과가 바로 바뀌어요.

템플릿의 팁 계산기 전체 코드예요. 슬라이더를 움직이면 1인당 금액·비교표·차트가 함께 바뀌어요.

// Tip Calculator - an Acard block plugin template (#144).
// Runs inside the Acard sandbox Worker, where the global `acard` exists (types: acard-plugin-sdk/src/types.d.ts).
// render(ctx) returns a UI tree; moving a slider sends an action ("change") with every control value, onAction runs,
// then render runs again with the same ctx - so the result recomputes on every change (Intelligent UI).
/// <reference path="../../acard-plugin-sdk/src/types.d.ts" />

const { ui } = acard;
const DEFAULTS = { amount: 60000, percent: 15, people: 3 };
const CURRENCY = { KRW: { symbol: "₩", step: 1000, max: 500000, digits: 0 }, USD: { symbol: "$", step: 1, max: 1000, digits: 2 }, EUR: { symbol: "€", step: 1, max: 1000, digits: 2 }, JPY: { symbol: "¥", step: 100, max: 50000, digits: 0 } };

function money(value, cur) {
  return cur.symbol + value.toLocaleString("en-US", { minimumFractionDigits: cur.digits, maximumFractionDigits: cur.digits });
}

// The values on screen: set by onAction, else what this block saved last time (ctx.state), else the defaults.
let current = null;

function clamp(src, cur) {
  const pick = (key, min, max) => {
    const n = Number(src[key]);
    return Number.isFinite(n) ? Math.min(max, Math.max(min, n)) : DEFAULTS[key];
  };
  return { amount: pick("amount", 0, cur.max), percent: pick("percent", 0, 30), people: Math.round(pick("people", 1, 20)) };
}

acard.block("tip", {
  async onAction(ctx, action) {
    const cur = CURRENCY[ctx.settings.currency] || CURRENCY.KRW;
    current = action.name === "reset" ? { ...DEFAULTS } : clamp(action.values, cur);
    await ctx.setState(current); // the block remembers the last values in the page
  },

  render(ctx) {
    const en = ctx.lang === "en";
    const cur = CURRENCY[ctx.settings.currency] || CURRENCY.KRW;
    const v = clamp(current || ctx.state || DEFAULTS, cur);
    const tip = v.amount * v.percent / 100;
    const total = v.amount + tip;
    const each = total / v.people;
    const options = [10, 15, 20].map((p) => {
      const t = v.amount * (1 + p / 100);
      return [p + "%" + (p === v.percent ? " ✓" : ""), money(v.amount * p / 100, cur), money(t, cur), money(t / v.people, cur)];
    });

    return [
      ui.heading(en ? "Tip calculator" : "팁 계산기"),
      ui.slider("amount", en ? "Bill" : "금액", v.amount, 0, cur.max, cur.step),
      ui.grid(2,
        ui.slider("percent", en ? "Tip %" : "팁 %", v.percent, 0, 30, 1),
        ui.slider("people", en ? "People" : "인원", v.people, 1, 20, 1)),
      ui.stats([
        { label: en ? "Per person" : "1인당", value: money(each, cur) },
        { label: en ? "Tip" : "팁", value: money(tip, cur), delta: "+" + v.percent + "%" },
        { label: en ? "Total" : "합계", value: money(total, cur) },
      ]),
      ui.compare([en ? "Tip" : "팁", en ? "Tip amount" : "팁 금액", en ? "Total" : "합계", en ? "Per person" : "1인당"], options),
      ui.chart("bar", Array.from({ length: Math.min(v.people, 10) }, (_, i) => String(i + 1)),
        [{ name: en ? "Share" : "몫", data: Array.from({ length: Math.min(v.people, 10) }, () => Math.round(each * 100) / 100) }], cur.symbol),
      ui.row(ui.button(en ? "Reset" : "처음 값으로", "reset")),
    ];
  },
});

명령 플러그인

명령은 편집기에서 / 를 누르면 나오는 플러그인 묶음과 빈 줄에서 Tab 으로 여는 기능 찾기에 나와요. 사용자가 고르면 숨은 칸에서 run(ctx) 이 한 번 돌고, 고른 블록 뒤에 ctx.insert(markdown) 로 한 번 쓸 수 있어요(page:write 권한, 64 KB 까지). 전체 실행은 5초 안에 끝나야 해요. 명령은 블록이 없어서 ctx.setState 는 쓸 수 없어요.

{
  "id": "insert-date",
  "name": "Insert Date",
  "version": "1.0.0",
  "minAppVersion": "1",
  "description": "Adds today's date after the block you picked the command on.",
  "author": "Your Name",
  "license": "MIT",
  "permissions": ["page:write"],
  "contributes": { "commands": [{ "id": "today", "name": "오늘 날짜 넣기", "description": "2026년 10월 24일 (토)" }] },
  "settings": [{ "key": "format", "type": "select", "label": "날짜 모양", "default": "long", "options": [{ "value": "long", "label": "2026년 10월 24일 (토)" }, { "value": "iso", "label": "2026-10-24" }] }]
}

// main.js - 빌드 없이 그대로 써요.
const DAYS = ["일", "월", "화", "수", "목", "금", "토"];
function dateText(format) {
  const d = new Date();
  const iso = d.getFullYear() + "-" + String(d.getMonth() + 1).padStart(2, "0") + "-" + String(d.getDate()).padStart(2, "0");
  return format === "iso" ? iso : d.getFullYear() + "년 " + (d.getMonth() + 1) + "월 " + d.getDate() + "일 (" + DAYS[d.getDay()] + ")";
}

acard.command("today", {
  async run(ctx) {
    await ctx.insert(dateText(ctx.settings.format));
  },
});

전체 템플릿(회의 메모 머리말 명령 포함)은 packages/acard-plugin-template-command 에 있어요.

사이드 패널 플러그인

contributes.panel 이 있으면 편집기 오른쪽 위 더보기(···) 메뉴에 패널 이름이 생기고, 누르면 오른쪽(좁은 화면에서는 아래에서 올라오는 시트)에 패널이 열려요. 패널도 블록처럼 render · onAction 으로 그려요. 닫으면 패널의 Worker 가 함께 끝나고, 플러그인을 끄거나 회수하면 열린 패널도 닫혀요.

{
  "id": "word-stats",
  "name": "Word Stats",
  "version": "1.0.0",
  "minAppVersion": "1",
  "description": "Counts the words and characters of the open page in a side panel.",
  "author": "Your Name",
  "license": "MIT",
  "permissions": ["page:read"],
  "contributes": { "panel": { "name": "단어 통계", "icon": "▤" } }
}

// main.js - 지금 연 페이지를 읽어(page:read) 단어와 글자 수를 보여 줘요. 다시 세기를 누르면 다시 그려요.
acard.panel({
  async render(ctx) {
    const page = await ctx.page.read();
    const text = page.markdown.replace(/```[\s\S]*?```/g, " ");
    const words = text.split(/\s+/).filter(Boolean).length;
    const chars = text.replace(/\s/g, "").length;
    return [
      acard.ui.heading(page.title || "제목 없음", 3),
      acard.ui.stats([{ label: "단어", value: words.toLocaleString("ko-KR") }, { label: "글자", value: chars.toLocaleString("ko-KR") }]),
      acard.ui.button("다시 세기", "refresh"),
    ];
  },
});

CSS 플러그인

코드 없이 styles.css 하나로 Acard 의 색·글꼴·간격 토큰을 바꿔요. :root 와 :root[data-theme=dark] 의 토큰 변수, 그리고 .pl-<id> 로 시작하는 규칙만 쓸 수 있고, url() · @import · 이스케이프는 막혀요. Acard 가 검사하고 다시 써서 넣기 때문에 그대로 붙지 않아요. 템플릿은 packages/acard-plugin-template-css(파스텔 테마)예요.

API 레퍼런스

UI 트리 한도: 노드 400, 깊이 8, 문자열 2000자, 전체 64 KB. 문자열은 모두 이스케이프되고 **굵게** 와 ` 코드 만 살아요. 모르는 노드는 버려요. 타입은 packages/acard-plugin-sdk/src/types.d.ts` 에 있어요.

샌드박스: 어떻게 안전하게 도나요

• 플러그인 코드는 acard.dev 가 아닌 별도 사이트의 sandbox="allow-scripts" 프레임 안, 그 안의 전용 Worker 에서만 돌아요. Acard 의 쿠키·저장소·화면이 없는 곳이에요.
• 프레임의 응답 헤더 CSP 가 네트워크를 막아요. connect-src 는 manifest 의 network 주소뿐이고, 없으면 'none' 이에요.
• render 2초·명령 5초를 넘기거나(저장·페이지 읽기를 기다리는 시간은 빼고, 한 요청 최대 15초), 초당 2 MB 넘게 보내면 Worker 를 끝내고 "멈춤" 을 보여요.
• 공유·게시 페이지에서는 플러그인이 돌지 않아요. 편집자가 "공개 화면에 이 모습 쓰기" 로 저장한 정적 모습만 보여요.
• 오프라인이면 플러그인 블록·명령·패널은 실행하지 않아요.

옵시디언 플러그인과 다른 점

마켓에 내기

• 처음 낸 사람과 처음 낸 저장소가 그 id 의 주인이에요. 다른 저장소로 같은 id 를 낼 수 없어요.
• 승인되는 순간 그 릴리스의 파일을 우리 저장소에 해시와 함께 복사해요. 나중에 GitHub 저장소를 바꿔도 사용자는 승인된 사본만 받아요.
• GitHub 제출은 1시간에 5번, 한 번에 하나씩이에요.

승인 기준과 자주 거절되는 이유

회수가 일어나면

사용자는 상세 화면의 신고 로 문제를 알릴 수 있고(사유 6가지, 하루 5건), 관리자는 신고를 보고 기각하거나 회수해요. 관리자가 회수하면 마켓에서 바로 내려가고, 새로 여는 페이지에서는 실행되지 않아요. 이미 열려 있는 탭은 다음 권한 호출 때나 실행 허가(5분)가 끝날 때 멈춰요. 같은 코드는 zip 으로도 다시 설치할 수 없어요.