Obsidian Excalidraw 캔버스 빌더
Obsidian Excalidraw 플러그인에서 올바르게 열리는 .excalidraw.md 파일을 생성합니다. 핸드라이팅 LaTeX 블록, 연결 화살표, 테마에 맞는 색상을 포함합니다.
사용 시기
- 볼트 내에서 지식 맵 / 의사 결정 트리 / 수식 보드를 Excalidraw 캔버스로 구축할 때
- Markdown 개요나 노트를 시각적 캔버스로 변환할 때
- 깨진 이미지, 보이지 않는 텍스트, 거대한 수식, 예상치 못한 흰색/어두운 배경으로 렌더링되는 캔버스를 수정할 때
- 새 캔버스를 같은 볼트에 있는 기존 캔버스의 시각적 언어와 일치시킬 때
웹 앱에 전달할 독립형 .excalidraw JSON이나 PNG/SVG 렌더링에는 사용하지 마십시오. 구분이 필요한 경우 references/when-not-to-use.md를 참조하십시오.
황금률 (어렵게 배운 교훈)
- LaTeX는 텍스트가 아닙니다. 수식은
type: "image"요소이며, 그 소스는## Embedded Files섹션에<40-hex-id>: $$tex$$형식으로 존재합니다. 일치하는 Embedded Files 항목이 없는 이미지 요소는 깨진 이미지로 렌더링됩니다.references/latex.md를 참조하십시오. - 이 플러그인에서는 텍스트 요소 내에
$$...$$를 직접 작성하지 마십시오. 원시 소스가 표시됩니다. 플러그인은 Embedded Files에 존재하는 수식만 렌더링합니다. - 씬 테마는 권위적이지 않습니다. 플러그인은
appState.theme를 앱 수준 테마로 덮어씁니다. 따라서 캔버스 색상은viewBackgroundColor에서 오지만, 밝은 테마는 배경을 흰색으로 칠합니다.references/theme-and-color.md를 참조하십시오. - 색상을 새로 만들기 전에 같은 볼트의 기존 캔버스에서 팔레트를 복사하십시오.
scripts/inspect_canvas.mjs로 하나를 압축 해제하고, 획 색상과 글꼴 패밀리를 읽어 재사용하십시오. - 균일한 수식 높이, 길이 기반 너비. 고정된 큰 너비는 짧은 수식을 거인으로 늘립니다.
references/layout.md를 참조하십시오. - 플러그인은
compressed-json으로 다시 저장합니다. (LZString base64, 약 120자마다 줄바꿈). 저장된 파일을 패치하는 대신 생성기 스크립트에서 캔버스를 다시 생성하십시오. 읽으려면 압축 해제가 필요합니다.scripts/inspect_canvas.mjs가 이를 수행합니다. - 성공을 주장하기 전에 확인하십시오. 검사 스크립트를 실행하고 확인: 수식 개수가 이미지 개수와 일치, 떠 있는 바인딩 없음, 테마/배경이 의도한 대로.
- "좋아 보인다"는 측정 가능합니다. 컨테이너 비율 ≤ 30%, 글꼴 크기 종류 ≤ 4, 수식 높이 분산 0, 겹침 개수 0.
scripts/inspect_canvas.mjs는 이제 이를 '심미적 경고'로 출력합니다. 어떤 경고든 선호도가 아니라 결함으로 처리하십시오.references/design-metrics.md를 참조하십시오. - 한 번 작성하고, 안정적인 ID를 사용하며, 먼저 삭제하십시오. 요소 ID는 내용(텍스트/TeX/레이블의 해시)에서 파생되어야 하며, 절대 무작위가 아니어야 합니다. 그리고 대상 파일을 쓰기 전에 연결을 해제하십시오. 둘 다 없으면 Obsidian에서 현재 열려 있는 캔버스를 다시 생성할 때 새 요소가 라이브 씬에 병합됩니다: 모든 것이 두 배로 늘어나고, 플러그인은 두 배가 된 씬을 디스크에 자동 저장합니다.
references/troubleshooting.md→ "요소가 두 배/세 배로 늘어남"을 참조하십시오. - 전달하기 전에 렌더링하십시오.
scripts/render_preview.mjs는 헤드리스(Node, 브라우저 없음)로 파일을 래스터라이즈합니다. PNG를 보십시오. JSON 감사는 구조를 잡아내고, 픽셀만이 "간격이 이상하다"를 잡아냅니다. LaTeX는 해당 미리보기에서 빈 상태로 나옵니다(MathJax는 Obsidian 플러그인에 있으며 렌더러에는 없음). 따라서 레이아웃은 거기서 판단하고 수식 정확성은## Embedded Files에서 판단하십시오. $$레이어는 하나만. 데이터 모델의 TeX는 베어입니다 (A=\int…). 구분 기호는## Embedded Files라인을 내보낼 때만 추가됩니다. 생성된 파일에$$$가 있으면 리터럴 달러 기호를 렌더링하는 이중 래핑 버그입니다.
두 가지 레이아웃 학교 — 그리기 전에 선택하십시오
| 컬럼 그리드 (表格派) | 라인으로 구조화 (结构派) | |
|---|---|---|
| 모양 | 컬럼 상자 + 행 구분선 | 트렁크 라인 + 드롭 라인 + 자유 부동 텍스트 |
| 컨테이너 비율 | 높음 (컬럼당 상자) | 거의 0 |
| 읽히는 방식 | 조회 테이블, 엄격함 | 칠판 스타일, 가벼움 |
| 최적 대상 | 셀 단위로 검사하는 많은 동일 수준의 행 | 분기 또는 서로 파생되는 컬럼 |
| 실패 모드 | "슬라이드 템플릿 같아 보임" | 너무 많은 분기 → 선 교차 |
경험 법칙: 형제 컬럼 → 컬럼 그리드; 하나의 컬럼이 다른 컬럼에서 파생됨 → 구조 라인. 두 예제 모두 design-metrics.md에 동일한 내용(第十講 캔버스)으로 존재하므로 선택 전에 비교할 수 있습니다.
워크플로우
- 대상 볼트 규칙을 읽으십시오. 사용자가 마음에 들어하는 기존
.excalidraw.md를 찾고,node scripts/inspect_canvas.mjs <파일>을 실행하여 테마,viewBackgroundColor, 주 획 색상,fontFamily,roughness, 일반적인 글꼴 크기를 기록하십시오. - 내용을 컬럼 또는 행으로 설계하십시오. (
references/layout.md참조) — 수량/단계 패밀리당 하나의 컬럼, 공식당 하나의 행, 그리고 실제로 동일한 수량인 것만 그룹화하십시오. 위 표에 따라 레이아웃 학교(컬럼 그리드 vs 구조 라인)를 선택하십시오. - 생성기 스크립트를 작성하십시오.
scripts/gen_canvas.mjs를 모델로:CONFIG블록(제목, 컬럼, 행)을 편집하고 실행하십시오. 30kB JSON을 직접 편집하지 마십시오. 함께 제공되는 두 가지 안전 메커니즘을 유지하십시오: 내용 기반 ID 및writeFileSync전의rmSync. - 결과를 검사하십시오.
scripts/inspect_canvas.mjs로 개수/색상/바인딩을 수정하십시오. 또한 파일에$$$가 없는지, 요소 개수가 생성기가 출력한 것과 일치하는지 확인하십시오(배수이면 병합 버그가 발생한 것입니다). 그런 다음scripts/render_preview.mjs로 렌더링하고 실제로 PNG를 보십시오. 간격/겹침/짧은 선을 보고하기 전에 수정하십시오. - 보고하십시오. 사용자가 Obsidian에서 무엇을 해야 하는지 알려주십시오(파일을 닫았다 다시 열거나, "현재 Excalidraw 파일 압축 풀기" 명령 사용) — 플러그인은 파일이 다시 열릴 때만 다시 읽습니다.
참조 맵
| 파일 | 내용 |
|---|---|
references/file-format.md | 정확한 .excalidraw.md 스켈레톤, 두 인코딩, 섹션 순서, 헤더 주석 |
references/element-schema.md | 요소 유형별 필수 필드, 바운드 텍스트, 화살표 바인딩, index 순서 |
references/latex.md | Embedded Files 계약, \color, 크기 조정, 테스트된 세 가지 렌더링 변형, 실패 서명 |
references/theme-and-color.md | 캔버스가 흰색으로 열리는 이유, matchThemeAlways, 팔레트 추출, 이 볼트의 설정된 색상 |
references/layout.md | 컬럼/행 지오메트리, 수식 크기 조정 휴리스틱, 캔버스가 미완성으로 보이게 만드는 요소 |
references/script-engine.md | 플러그인 내 JS 스크립트 엔진: 스크립트 위치, 할 수 있는 일, ExcalidrawAutomate API, 테이블 가능 여부, 파일 수준 생성과의 절충 |
references/design-metrics.md | 계량화된 미학: 컨테이너 비율, 글꼴 수준 개수, 수식 분산, 공백, 의미적 색상; 두 레이아웃 학교; 렌더러 없이 검증하는 방법 |
references/troubleshooting.md | 지금까지 본 모든 실패에 대한 증상 → 원인 → 수정 표 |
scripts/gen_canvas.mjs | 구성 기반 캔버스 생성기 (텍스트, latex, rect, hline, arrow) |
scripts/inspect_canvas.mjs | 압축 해제 + 감사: 테마, 개수, 수식/이미지 일치, 바인딩, 글꼴, 미적 메트릭. --describe는 간결한 id/위치/레이블/연결 인벤토리 출력; --dump는 원시 씬 JSON 출력 |
scripts/render_preview.mjs | mcp-excalidraw-server render를 통한 헤드리스 PNG 미리보기 (브라우저 없음). LaTeX는 빈 상태로 렌더링 — 레이아웃 전용 |
evals/evals.json | 회귀 프롬프트: 실제 발생한 실패 모드당 하나 |
examples/ea-table.md | 사각형 + 텍스트로 테이블을 만드는 실행 가능한 인앱 스크립트 |
기존 캔버스 편집
- 현재 상태를 이해하기 위해 압축을 푸십시오 (
inspect_canvas.mjs --dump <파일>은 씬 JSON을 출력합니다). - 생성기 스크립트에서 다시 생성하는 것을 선호하십시오. 사용자가 수동으로 편집한 내용을 유지할 가치가 있다면, 전체 캔버스를 다시 쓰는 대신 범위가 지정된 변환(씬 읽기 → 특정 요소 변경 → 압축되지 않은 상태로 다시 직렬화)을 작성하십시오.
- 캔버스를 절반만 마이그레이션된 상태로 두지 마십시오: 모든 이미지에 해당 수식이 있거나, 아예 없거나.
이 볼트의 크기 및 타이포그래피 기본값
- 본문 텍스트
fontFamily: 6,roughness: 0,strokeWidth: 1. - 제목 28–30px, 컬럼 헤더 19–22px, 행 레이블 15–16px, 수식 이미지 높이 50–52px.
- 행 간격 116–130px; 컬럼 너비 320–340px; 간격 28–40px.
- 캔버스 배경
#ffffff; 잉크#1e1e1e; 억제된 색#868e96; 가는 선#e9ecef.