# oxdraw - 코드 기반 다이어그램 도구

> Clean Markdown view of GeekNews topic #23931. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=23931](https://news.hada.io/topic?id=23931)
- GeekNews Markdown: [https://news.hada.io/topic/23931.md](https://news.hada.io/topic/23931.md)
- Type: GN+
- Author: [neo](https://news.hada.io/@neo)
- Published: 2025-10-27T01:34:39+09:00
- Updated: 2025-10-27T01:34:39+09:00
- Original source: [github.com/RohanAdwankar](https://github.com/RohanAdwankar/oxdraw)
- Points: 25
- Comments: 1

## Summary

**oxdraw**는 **Mermaid 문법 기반 다이어그램을 코드처럼 관리하면서도 시각적으로 편집할 수 있는 ‘Diagram as Code’ 도구**입니다. Rust로 구현된 **CLI 렌더러**와 React 기반 **웹 편집기**를 결합해, 코드의 재현성과 GUI의 자유도를 동시에 제공합니다. 수정 내용이 **Mermaid 파일 내 주석으로 저장**되어 기존 도구와의 호환성을 유지하면서도, **버전 관리·자동화 파이프라인**에 자연스럽게 녹아듭니다.

## Topic Body

- **oxdraw**는 Rust로 작성된 **‘Diagram as Code’ 도구**로, 코드 기반 다이어그램을 시각적으로 편집하고 재현 가능한 형태로 유지하도록 설계됨  
- 다이어그램은 **Mermaid 문법**으로 작성되며, 웹 인터페이스를 통해 노드 위치, 색상, 연결선 등을 **드래그로 조정** 가능  
- 시각적 수정 내용은 **Mermaid 파일 내 주석 형태로 저장**되어 다른 Mermaid 도구와의 호환성을 유지함  
- CLI와 React 기반 웹 편집기로 구성되어 있으며, **명령줄 렌더링과 실시간 편집 모드** 모두 지원  
- 코드 생성형 다이어그램의 생산성과 시각적 편집의 자유도를 결합해, **Lucidchart와 같은 GUI 도구의 대안**으로 주목받음  
  
---  
  
### 프로젝트 개요  
- **oxdraw**의 목표는 선언적이고 재현 가능한 문법을 통해 **고품질 다이어그램을 쉽게 생성·유지**하는 것임  
  - 다이어그램은 Mermaid 문법으로 작성되며, 시각적 조정은 웹 인터페이스에서 수행  
  - 사용자가 시각적으로 수정한 내용은 원본 코드에 반영되어 **버전 관리와 자동화**가 가능  
- 수정 내용은 Mermaid 파일 내 **주석(comment)** 형태로 기록되어, Mermaid 생태계의 다른 도구와 **완전한 호환성** 유지  
- 저장소는 **Rust 기반 CLI**와 **React 기반 웹 인터페이스**로 구성되어 있으며, CLI는 `.mmd` 파일을 이미지로 컴파일함  
  
### 프로젝트 비전  
- 개발자는 과거 **Mermaid**를 활용해 아키텍처 다이어그램이나 코드베이스 시각화를 수행했으나, **세밀한 편집 한계**로 인해 Lucidchart 등으로 옮겨야 했음  
- oxdraw는 **Mermaid의 코드 기반 자동화**와 **Lucidchart의 시각적 자유도**를 결합하는 것을 목표로 함  
- 이를 통해 코드 생성형 다이어그램의 **재현성, 협업성, 자동화 가능성**을 유지하면서도, **시각적 완성도**를 높이는 방향을 지향  
  
### 사용 방법  
- **Cargo**를 통해 설치 가능: `cargo install oxdraw`  
- 다이어그램 렌더링: `oxdraw --input flow.mmd`  
- **인터랙티브 편집기 실행**: `oxdraw --input flow.mmd --edit`  
- CLI는 Mermaid 파일을 입력받아 **SVG 또는 PNG 출력**을 생성하며, `--edit` 옵션으로 **로컬 웹 편집기**를 실행  
  
### CLI 플래그 설명  
- `-i, --input `: Mermaid 소스 파일 입력  
- `-o, --output `: 렌더링 결과물 저장 경로 지정  
- `--png`: PNG 형식으로 출력  
- `--scale `: PNG 렌더링 배율 조정 (기본값 10.0)  
- `--edit`: 시각적 편집기 실행  
- `--serve-host ` / `--serve-port `: 편집기 서버의 주소 및 포트 지정 (기본 127.0.0.1:5151)  
- `-b, --background-color `: 배경색 지정 (SVG 전용)  
- `-q, --quiet`: 렌더링 완료 메시지 등 출력 억제  
  
### 프런트엔드 기능  
- **노드 및 엣지 조작**  
  - 선택된 노드나 엣지 삭제 (Delete/Backspace 키 지원)  
  - 노드 색상, 테두리, 텍스트 색상 개별 지정 및 초기화  
  - 엣지 색상, 선 스타일(실선/점선), 화살표 방향 설정  
  - 엣지 경로에 **드래그 가능한 제어점(control point)** 추가 및 제거  
- **캔버스 및 편집기 상호작용**  
  - 노드 드래그 시 **격자 스냅 및 정렬 가이드** 표시  
  - Shift+화살표로 노드 이동  
  - 엣지 핸들을 드래그해 경로 수정, 더블클릭으로 핸들 추가/삭제  
  - **서브그래프 단위 이동** 지원 — 그룹 내 노드 및 엣지 함께 이동  
  - **소스 패널**은 Mermaid 파일을 실시간 반영하며, 자동 저장 및 상태 표시(저장 중/오류 등) 제공  
  - 상단 툴바에는 현재 파일 경로 및 저장 상태 표시  
  
### 기술 구성 및 라이선스  
- **Rust 55.7%** , **TypeScript 40.0%** , **CSS 3.4%** , 기타 0.9%로 구성  
- **MIT 라이선스**로 공개되어 자유로운 사용 및 수정 가능  
- 현재 **506개의 Star**, **10개의 Fork**를 보유하며, 활발한 커뮤니티 관심을 받고 있음  
  
### 종합 평가  
- oxdraw는 **코드 기반 다이어그램 관리의 자동화**와 **시각적 편집의 직관성**을 결합한 새로운 접근  
- Mermaid 생태계와의 **완전한 호환성**을 유지하면서, **Rust의 성능**과 **React의 인터랙티브 UI**를 활용  
- 개발자와 디자이너 모두에게 **협업 가능한 다이어그램 워크플로우**를 제공하는 도구로 주목받는 중

## Comments



### Comment 45489

- Author: neo
- Created: 2025-10-27T01:34:40+09:00
- Points: 1

###### [Hacker News 의견](https://news.ycombinator.com/item?id=45706792) 
- 정말 멋진 프로젝트임. **Mermaid.js**를 기반으로 한 선택이 현 시점에서 가장 인기 있는 선언적 다이어그램 라이브러리라 생각함  
  더 복잡한 다이어그램 타입을 지원하려면 [**D2 Language**](https://d2lang.com/)도 살펴볼 만함. 훨씬 **유연한 선언적 접근법**을 제공함  

- 개인적으로 **MacPorts 포트**를 만들어서 사용 중임  
  자주 쓰게 되면 [공식 MacPorts 저장소](https://github.com/macports/macports-ports)에 기여할 생각임  
  다만 Cargo 릴리스와 연동된 **Git 태그나 GitHub 릴리스**가 없어서 패키징이 불편함  
  지금은 특정 커밋(`9ccd9bf53f9a309ccda42b5c17e9c1056493fb90`)을 0.1.0 릴리스로 가정해 임시로 해결 중임  
  관련 포트는 [여기](https://github.com/halostatue/ports)에서 볼 수 있음  

- 이 프로젝트는 정말 내가 찾던 바로 그거임. **선언적 다이어그램** 솔루션에서 꼭 보고 싶은 기능이 있음  
  바로 마우스 오버 시 **추가 정보나 중첩 다이어그램**을 보여주는 팝업 기능임  
  - 흥미로운 아이디어임. 혹시 그 팝업은 개인용인지, 아니면 팀원에게 공유하기 위한 용도인지 궁금함  
    예를 들어 링크를 공유하면 팝업과 중첩이 포함된 다이어그램을 바로 볼 수 있게 하고 싶은 건지,  
    아니면 `.mmd` 파일만 공유해서 CLI로 열면 되는 수준이면 충분한지 알고 싶음  
    후자는 금방 구현 가능하지만, 전자는 **ngrok 같은 셀프 호스팅**이나 **클라우드 배포**가 필요할 수도 있음  
    혹은 **HTML 파일로 내보내기(export)** 기능을 추가해 CLI 없이도 팝업이 작동하도록 할 수도 있음  

- 프로젝트 공개를 축하함. 선언적 문법으로 관계를 정의하고, 기존 자동 레이아웃이 못 하는 **세밀한 커스터마이징**을 가능하게 한 점이 인상적임  
  다만 `Cargo.toml`에는 MIT 라이선스로 표시되어 있지만, 저장소에 **라이선스 파일이 없음**  
  GitHub에서 바로 확인할 수 있도록 추가해주면 좋겠음  
  - 도구의 **채택률을 높이려면 호스팅**을 고려해보길 권함. 서버 사이드 코드 의존도가 높아 무료 정적 호스팅은 어려워 보임  
  - 라이선스 파일 추가 완료함. 알려줘서 고마움  

- 정말 필요한 프로젝트임. 나는 주로 **PlantUML**을 쓰는데, 컴포넌트가 5개만 넘어도 레이아웃 조정에 20~30%의 시간을 씀  
  주석을 활용해 레이아웃 엔진에 반영하는 접근이 흥미로움. 특정 컴포넌트의 좌표를 **고정된 제약조건**으로 두고 나머지를 자동 배치하는 방식이 유용할 듯함  
  코드 변경과 함께 다이어그램도 버전 관리에 포함되면 **코드 리뷰와 아키텍처 관리**가 훨씬 자연스러워짐  
  - 나도 GitLab에서는 PlantUML을 쓰지만, GitHub에서는 Mermaid를 써야 해서 번거로움  
    **Mermaid의 레이아웃 품질이 낮고**, GitHub가 PlantUML 지원 요청을 무시하는 게 아쉬움  
    주요 플랫폼이 지원하는 포맷에 따라 **‘diagrams as code’의 채택률**이 결정되는 듯함  
    새로운 표준을 만드는 것보다는, **요소 가중치 기반 렌더링** 같은 개선이 더 현실적이라 생각함  
    관련 논의는 [GitHub 커뮤니티 토론](https://github.com/orgs/community/discussions/10111)에서도 다뤄지고 있음  

- **PlantUML**이 이런 문제를 해결해줬으면 좋겠다는 바람이 큼  

- 이건 마치 **Graphviz의 dot 언어를 강화한 버전** 같음  
  변수와 더 깔끔한 문법을 제공하지만 기본 개념은 유사함  
  [Graphviz 문서](https://graphviz.org/doc/info/lang.html) 참고  

- **Mermaid.js**에는 레이아웃 엔진 개념이 있음  
  [@mermaid-js/layout-elk](https://www.npmjs.com/package/@mermaid-js/layout-elk)처럼  
  혹시 네 알고리즘을 **Mermaid용 자동 레이아웃 엔진**으로 구현할 생각은 없는지 궁금함  

- 멋진 프로젝트임. 모바일에서 봤는데 **노드 추가 버튼**이 안 보임  
  또 하나 바라는 기능은 **하위 노드 접기(collapse downstream nodes)** 기능임. 범위를 벗어날 수도 있지만 있으면 좋겠음  
  - 현재는 `.mmd` 텍스트를 직접 수정해야 함. 하지만 좋은 제안이라 생각함  
    하위 노드 접기 기능은 다른 사용자가 요청한 **애니메이션 기능**과도 잘 맞을 듯