SVG 그래픽

VMark는 SVG — 확장 가능한 벡터 그래픽 — 를 최우선으로 지원합니다. 문서에서 SVG를 사용하는 방법에는 두 가지가 있으며, 각각 다른 워크플로우에 적합합니다.

방법	적합한 경우	소스 편집 가능?
이미지 임베드 ()	디스크의 정적 SVG 파일	아니오
코드 블록 (```svg)	인라인 SVG, AI 생성 그래픽	예

이미지로 SVG 임베드

표준 마크다운 이미지 구문을 사용하여 SVG 파일을 임베드합니다:

![Architecture diagram](./assets/architecture.svg)

이는 PNG 또는 JPEG 이미지와 정확히 같은 방식으로 작동합니다 — 드래그 앤 드롭, 붙여넣기, 또는 툴바를 통해 삽입합니다. SVG 파일은 이미지로 인식되고 인라인으로 렌더링됩니다.

사용 시기: Figma, Illustrator, Inkscape 또는 디자인 도구에서 가져온 .svg 파일이 있고 문서에 표시하고 싶을 때.

제한 사항: SVG가 정적 이미지로 렌더링됩니다. SVG 소스를 인라인으로 편집할 수 없으며, 패닝+줌이나 내보내기 컨트롤이 나타나지 않습니다.

SVG 코드 블록

svg 언어 식별자와 함께 펜스드 코드 블록에 원시 SVG 마크업을 감쌉니다:

```svg
<svg viewBox="0 0 200 100" xmlns="http://www.w3.org/2000/svg">
  <rect width="200" height="100" rx="10" fill="#4a6fa5"/>
  <text x="100" y="55" text-anchor="middle" fill="white"
        font-size="18" font-family="system-ui">Hello SVG</text>
</svg>
```text

SVG는 Mermaid 다이어그램처럼 인라인으로 렌더링되며 대화형 컨트롤이 포함됩니다.

VMark 고유 기능

Typora나 Obsidian은 ```svg 코드 블록을 지원하지 않습니다. 이는 Mermaid의 문법에 맞지 않는 SVG 시각화 (차트, 일러스트레이션, 아이콘)를 생성하는 AI 워크플로우를 위해 설계된 VMark 전용 기능입니다.

코드 블록 사용 시기

• AI 생성 그래픽 — Claude, ChatGPT 및 다른 AI 도구가 SVG 차트, 다이어그램, 일러스트레이션을 직접 생성할 수 있습니다. SVG를 코드 블록에 붙여넣으면 인라인으로 렌더링됩니다.
• 인라인 SVG 작성 — 문서에서 SVG 소스를 직접 편집하고 실시간 결과를 확인합니다.
• 자체 포함 문서 — SVG가 마크다운 파일 안에 있어 외부 파일 의존성이 없습니다.

WYSIWYG 모드에서 편집

리치 텍스트 모드에서 SVG 코드 블록은 자동으로 인라인으로 렌더링됩니다.

편집 모드 진입

렌더링된 SVG를 더블클릭하면 소스 에디터가 열립니다. 편집 헤더에 다음이 나타납니다:

버튼	동작
복사	SVG 소스를 클립보드에 복사
취소 (X)	변경 사항 되돌리기 및 종료 (Esc도 가능)
저장 (체크 표시)	변경 사항 적용 및 종료

에디터 아래의 실시간 미리보기 가 입력하면서 업데이트되어 변경 사항을 실시간으로 확인할 수 있습니다.

패닝 및 줌

렌더링된 SVG 위에 마우스를 올리면 대화형 컨트롤이 나타납니다:

동작	방법
줌	Cmd (macOS) 또는 Ctrl (Windows/Linux)를 누르고 스크롤
패닝	SVG를 클릭하여 드래그
초기화	초기화 버튼 클릭 (오른쪽 상단 모서리)

이는 Mermaid 다이어그램에 사용되는 것과 동일한 패닝+줌 컨트롤입니다.

PNG로 내보내기

렌더링된 SVG 위에 마우스를 올리면 내보내기 버튼이 나타납니다 (오른쪽 상단, 초기화 버튼 옆). 클릭하여 배경 테마를 선택합니다:

테마	배경
밝은	흰색 (#ffffff)
어두운	어두운 (#1e1e1e)

SVG는 시스템 저장 대화상자를 통해 2x 해상도 PNG로 내보내집니다.

소스 모드 미리보기

소스 모드에서 커서가 ```svg 코드 블록 안에 있으면 플로팅 미리보기 패널이 나타납니다 — Mermaid 다이어그램에 사용되는 것과 동일한 패널입니다.

기능	설명
실시간 미리보기	입력하면서 즉시 업데이트 (디바운스 없음 — SVG 렌더링은 즉각적)
이동하려면 드래그	헤더를 드래그하여 재배치
크기 조정	가장자리나 모서리를 드래그
줌	− 및 + 버튼, 또는 Cmd/Ctrl + 스크롤 (10% ~ 300%)

INFO

소스 모드 다이어그램 미리보기는 기본적으로 꺼져 있습니다. 보기 → 다이어그램 미리 보기 전환 (Alt + Mod + P) 또는 명령 팔레트로 켤 수 있습니다.

SVG 검증

VMark는 렌더링 전에 SVG 내용을 검증합니다:

• 내용이 <svg 또는 <?xml로 시작해야 합니다
• XML이 올바른 형식이어야 합니다 (파스 오류 없음)
• 루트 요소가 <svg>여야 합니다

검증에 실패하면 렌더링된 그래픽 대신 유효하지 않은 SVG 오류 메시지가 표시됩니다. 오류를 더블클릭하여 소스를 편집하고 수정합니다.

AI 워크플로우

AI 코딩 어시스턴트는 MCP 도구를 통해 VMark 문서에 직접 SVG를 생성할 수 있습니다. AI는 language: "svg"와 SVG 내용이 포함된 코드 블록을 전송하며, 자동으로 인라인으로 렌더링됩니다.

예시 프롬프트:

분기별 매출을 보여주는 막대 차트를 만들어 주세요: Q1 $2.1M, Q2 $2.8M, Q3 $3.2M, Q4 $3.9M

AI가 문서에 인라인으로 렌더링되는 SVG 막대 차트를 생성하며, 즉시 패닝+줌 및 PNG 내보내기를 사용할 수 있습니다.

비교: SVG 코드 블록 vs Mermaid

기능	```svg	```mermaid
입력	원시 SVG 마크업	Mermaid DSL
렌더링	즉각적 (동기적)	비동기 (200ms 디바운스)
패닝 + 줌	예	예
PNG 내보내기	예	예
실시간 미리보기	예	예
테마 적응	아니오 (SVG 자체 색상 사용)	예 (모든 테마에 적응)
적합한 경우	커스텀 그래픽, AI 생성 시각화	순서도, 시퀀스 다이어그램, 구조화된 다이어그램

팁

보안

VMark는 렌더링 전에 SVG 내용을 새니타이즈합니다. 스크립트 태그와 이벤트 핸들러 속성 (onclick, onerror 등)이 제거됩니다. 이는 신뢰할 수 없는 소스에서 SVG를 붙여넣을 때 XSS를 방지합니다.

외부 참조도 제거됩니다. <use>와 <image>는 같은 문서의 프래그먼트(href="#arrowhead")나 인라인 data:image/… 페이로드를 가리킬 수 있지만, 컴퓨터 밖을 가리키는 URL은 삭제됩니다. 이렇게 하지 않으면 신뢰할 수 없는 다이어그램이 포함된 문서를 여는 것만으로 그 URL을 가져오게 되어 — IP 주소와 파일을 연 시점이 드러납니다. Mermaid 같은 다이어그램 도구는 프래그먼트만 참조하므로 일반적인 다이어그램은 영향을 받지 않습니다.

SVG 자체의 스타일시트(<style>)는 그 SVG 안으로 제한됩니다. 모든 선택자가 원래의 SVG 안에서만 일치하도록 다시 작성되므로, 다이어그램이 에디터나 다른 다이어그램의 스타일을 바꿀 수 없습니다. 스타일 규칙, @media, @keyframes만 유지되며(애니메이션 이름은 SVG마다 고유하게 바뀜), @import, @font-face 및 기타 at-규칙, 외부 url() 참조, position: fixed / sticky는 삭제됩니다. <form> 요소는 제거됩니다(내용은 유지됨).

렌더링된 SVG 안의 링크는 VMark 자체를 이동시키지 않습니다. 웹 링크를 클릭하면 시스템 브라우저에서 열리고, 상대 파일 링크는 VMark 탭에서 파일을 열며, javascript:, file:, data: 링크는 절대 열리지 않습니다.

크기 지정

SVG에 명시적인 width/height 속성이 없는 경우 viewBox를 추가하여 종횡비를 제어합니다:

<svg viewBox="0 0 400 300" xmlns="http://www.w3.org/2000/svg">
  <!-- content -->
</svg>

내보내기 품질

PNG 내보내기는 레티나 화면에서 선명하게 표시하기 위해 2x 해상도를 사용합니다. 고체 배경색이 자동으로 추가됩니다 (SVG 자체에는 투명 배경이 있을 수 있습니다).