마크다운 파일 하나로 그리는 캔버스

이 프로젝트는 실험적 시도입니다.

Claude Code, Claude Desktop, Gemini CLI, Codex 같은 AI 에이전트가 가장 잘 하는 일은 두 가지입니다 — 로컬 파일을 읽고, 텍스트를 생성하는 것. 그리고 AI가 가장 빠르고 정확하게 다루는 포맷은 마크다운입니다.

Boardmark는 이 단순한 관찰에서 출발합니다. 별도의 API나 플러그인 없이, 사용자가 이미 구독하고 있는 AI 도구가 .md 파일을 직접 열고, 캔버스를 만들고, 편집할 수 있다면 어떨까. 마크다운은 사람도 쉽게 읽고 고칠 수 있고, AI는 토큰을 아끼면서 높은 품질로 생성할 수 있습니다.

핵심은 하나입니다. AI가 마크다운으로 캔버스를 그린다.

"AI가 구조를 만들고, 사람은 의미를 완성한다."

Boardmark는 아이디어, 설계, 흐름을 시각적으로 정리할 수 있는 텍스트 기반 캔버스입니다. 스티키 노트와 연결선을 보드 위에 펼치듯 구성하면서도, 모든 결과는 사람이 직접 읽고 수정할 수 있는 마크다운으로 유지됩니다. 별도의 포맷이나 전용 데이터 구조 없이, frontmatter에 type: canvas가 있는 .md 파일 하나가 곧 작업 공간이 됩니다.

기존 캔버스 도구들은 상태가 내부 구조에 묶여 협업과 버전 관리에 제약이 있었습니다. Boardmark는 이를 텍스트로 전환하여 git 기반의 변경 이력 관리와 코드 리뷰 흐름까지 자연스럽게 연결합니다. 결과적으로 문서와 설계, 시각적 사고가 하나의 파일 안에서 일관되게 관리됩니다.

각 노드는 :::note, :::edge, :::group 같은 마크다운 블록으로 표현되며, 위치와 크기, 색상 등의 정보는 YAML 메타데이터로 함께 정의됩니다. 이 구조는 사람이 직접 편집할 수 있을 뿐 아니라, AI 에이전트가 로컬 파일 시스템을 통해 캔버스를 생성하고 수정할 수 있는 인터페이스로 동작합니다.

:::note
x: 120
y: 80
w: 240
color: indigo
---

이 기능 구현해줘

:::

:::edge
from: note-1
to: note-2
:::

Boardmark는 텍스트와 시각적 표현을 분리하지 않습니다. 하나의 파일 안에서 사고를 펼치고, AI와 함께 구조를 만들며, 사람의 판단으로 내용을 정제하는 흐름을 제공합니다.

로컬 내부용 preview 배포는 정적 빌드 후 Vite preview 서버로 실행한다.

pnpm install
pnpm build:web
pnpm preview:web

기본 preview 서버는 127.0.0.1:4173에만 바인딩되므로 현재 머신에서만 접속할 수 있다.

같은 내부망 장비에서도 접속해야 하면 아래 명령을 사용한다.

pnpm preview:web:lan

이 경우 서버는 0.0.0.0:4173으로 열리므로 사내망이나 집 내부망에서만 접근되게 라우터/방화벽 범위 안에서 사용하면 된다.

Boardmark web 앱은 Vercel에서 루트 프로젝트로 배포한다. 루트 vercel.json이 apps/web만 빌드하고 apps/web/dist를 정적 결과물로 서빙한다.

Vercel 프로젝트 설정은 아래 값과 맞춘다.

Framework Preset: Vite
Install Command: pnpm install --frozen-lockfile
Build Command: pnpm build:web
Output Directory: apps/web/dist
Root Directory: .

GitHub 저장소를 Vercel에 연결하면 main은 production 배포가 되고, 그 외 브랜치는 preview 배포가 된다. 로컬에서 확인할 때는 아래 명령으로 같은 빌드를 재현한다.

pnpm install
pnpm build:web

공개 저장소로 전환하기 전에는 .env, .env.*, .vercel 같은 로컬 설정 파일이 커밋되지 않았는지 확인한다.

MIT