Excalidraw로 블로그 다이어그램 깔끔하게 관리하는 법

기술 블로그 다이어그램, 매번 고민되지 않나요?

기술 블로그를 운영하다 보면 다이어그램이 꼭 필요한 순간이 와요. 아키텍처 구조를 설명하거나, 데이터 흐름을 보여주거나, 시스템 간 관계를 그려야 할 때 말이에요. 그런데 어떤 도구를 쓸지가 은근히 고민이거든요. draw.io는 기능이 많지만 결과물이 좀 딱딱하고, Mermaid 같은 코드 기반 도구는 복잡한 다이어그램에선 한계가 있고요. 이런 고민을 하던 한 개발자가 Excalidraw의 프레임 내보내기(Frame Export) 기능을 활용해서 블로그 다이어그램 워크플로우를 깔끔하게 정리한 사례가 있어서 소개해 드릴게요.

Excalidraw, 왜 좋은가요?

Excalidraw는 오픈소스 화이트보드 도구인데, 가장 큰 특징은 손으로 그린 듯한 스케치 스타일이에요. 이게 왜 좋으냐면, 기술 문서에서 너무 깔끔한 다이어그램은 오히려 "이건 완성된 설계"라는 인상을 줘서 피드백을 받기 어렵게 만들거든요. 반면 스케치 느낌의 다이어그램은 "아직 논의 중"이라는 뉘앙스를 자연스럽게 전달해서, 블로그 독자들도 더 편하게 받아들이는 경향이 있어요.

게다가 Excalidraw는 .excalidraw 파일 형식이 사실 JSON이에요. 그래서 Git으로 버전 관리가 되고, 변경 이력을 추적할 수 있어요. 바이너리 이미지 파일을 Git에 넣으면 diff를 볼 수 없잖아요? Excalidraw 파일은 텍스트 기반이라 어떤 요소가 바뀌었는지 확인할 수 있어요.

프레임 내보내기 기능 활용법

이 워크플로우의 핵심은 Excalidraw의 '프레임(Frame)' 기능이에요. 프레임이 뭐냐면, 하나의 캔버스 안에서 특정 영역을 사각형으로 지정해놓는 거예요. 포토샵의 아트보드와 비슷한 개념이라고 생각하면 돼요.

실제 사용 방법은 이래요. 하나의 .excalidraw 파일 안에 블로그 글 하나에 필요한 다이어그램을 전부 그려놓고, 각 다이어그램을 프레임으로 감싸요. 그러면 프레임 단위로 개별 이미지를 내보낼 수 있어요. 예를 들어 한 블로그 포스트에 아키텍처 다이어그램, 시퀀스 다이어그램, 배포 흐름도 이렇게 세 개가 필요하면, 한 파일 안에 세 개의 프레임을 만들고 각각 따로 PNG나 SVG로 내보내는 거죠.

이렇게 하면 관리가 엄청 편해져요. 다이어그램이 여러 파일에 흩어져 있으면 나중에 스타일을 통일하기도 어렵고, 어떤 파일이 어떤 글에 쓰이는지 추적하기도 힘들잖아요. 한 파일에 모아두면 공통 컴포넌트(서버 아이콘, DB 아이콘 등)를 복사해서 일관성 있게 쓸 수 있어요.

자동화까지 연결하면 더 강력해져요

여기서 한 발 더 나아갈 수도 있어요. Excalidraw는 CLI 도구나 Node.js 라이브러리를 통해 프로그래밍 방식으로 내보내기가 가능하거든요. 블로그를 정적 사이트 생성기(Hugo, Gatsby, Next.js 블로그 등)로 운영한다면, 빌드 스크립트에서 .excalidraw 파일을 읽어서 자동으로 이미지를 생성하도록 만들 수 있어요. 다이어그램을 수정하면 Git에 커밋하고, 빌드 시 자동으로 최신 이미지가 반영되는 거죠.

이렇게 하면 "다이어그램 수정 → 이미지 내보내기 → 블로그 디렉토리에 복사 → 커밋" 이라는 수동 과정이 사라지고, "다이어그램 수정 → 커밋" 두 단계로 줄어들어요.

다른 도구들과 비교

비슷한 역할을 하는 도구들을 잠깐 비교해 볼게요. draw.io(diagrams.net)는 기능은 풍부하지만 파일 포맷이 XML 기반이라 Git diff가 읽기 어렵고, 스타일이 기업 문서에 가까워요. Mermaid는 코드로 다이어그램을 정의하는 방식이라 Git 친화적이지만, 레이아웃을 세밀하게 제어하기 어려워요. tldraw는 Excalidraw와 비슷한 컨셉인데, 프레임 내보내기 같은 배치 워크플로우 기능은 아직 부족한 편이에요.

Excalidraw의 장점은 이 사이의 균형을 잘 잡고 있다는 점이에요. 시각적 편집의 자유도가 높으면서도 텍스트 기반 파일 포맷이라 개발자 워크플로우에 잘 녹아들거든요.

한국 개발자에게 추천하는 이유

한국에서 기술 블로그를 운영하는 개발자분들이 정말 많은데, 다이어그램 때문에 글쓰기를 미루는 경우를 종종 봐요. "그림 그리기 귀찮아서..."라는 이유로요. Excalidraw는 진입 장벽이 낮고 결과물도 보기 좋아서, 다이어그램 때문에 글을 못 쓰고 있었다면 한번 시도해볼 만해요. VS Code 확장도 있어서 에디터를 떠나지 않고 바로 그릴 수 있고요.

특히 사내 기술 문서를 작성할 때도 유용해요. Notion이나 Confluence에 이미지로 붙여넣는 대신 .excalidraw 파일을 Git 레포에 함께 관리하면, 문서와 다이어그램의 버전이 항상 동기화되니까요.

한줄 정리: Excalidraw의 프레임 기능을 활용하면 하나의 파일에서 여러 다이어그램을 관리하고 개별 내보내기까지 깔끔하게 해결할 수 있어요.

여러분은 기술 블로그나 문서에서 다이어그램을 어떻게 관리하고 계세요? 좋은 워크플로우가 있다면 공유해 주세요!