mermaid markdown diagrams flowchart documentation

Markdown에서 Mermaid 사용하기: 순서도, 시퀀스 다이어그램 등

복사 가능한 순서도, 시퀀스, 클래스, Gantt, 마인드 맵 및 ER 다이어그램 예제와 미리 보기, 내보내기, 호환성 및 접근성 지침을 통해 Markdown에 대한 Mermaid 구문을 알아보세요.

W
WordToMD 팀
·

기술 다이어그램을 편집하려면 원본 디자인 파일을 찾고, 별도의 애플리케이션을 열고, 다른 이미지를 내보내야 하기 때문에 오래된 것이 되는 경우가 많습니다.Mermaid에서는 다른 접근 방식을 취합니다. 다이어그램은 텍스트로 정의되고 문서 옆에 저장됩니다.

Mermaid를 Markdown에 추가하려면 다이어그램 정의를 다음과 함께 분리된 코드 블록 안에 배치하세요. mermaid 언어 식별자.사용 Mermaid 다이어그램 미리보기 에서는 구문을 로컬로 렌더링하고, 오류를 수정하고, 전체 Markdown 펜스를 복사하거나 SVG를 다운로드합니다.

이 가이드는 작은 순서도부터 시작하여 시퀀스, 클래스, 간트, 마인드 맵 및 엔터티 관계 다이어그램을 구축합니다.

Mermaid 30초 내

기본 Mermaid 블록은 다음과 같습니다:

```mermaid
flowchart LR
  Draft --> Review
  Review --> Publish
```

여는 펜스는 호환되는 렌더러에게 콘텐츠가 Mermaid 구문임을 알려줍니다. flowchart LR 는 왼쪽에서 오른쪽으로 배열된 순서도를 선택합니다.나머지 줄은 노드와 연결을 정의합니다.

대상이 Mermaid를 지원하지 않는 경우 독자는 일반적으로 다이어그램 대신 코드 블록을 보게 됩니다.해당 폴백은 소스를 보존하지만 게시하기 전에 호환성을 확인하는 것을 대체하지는 않습니다.

텍스트 기반 다이어그램을 사용하는 이유는 무엇입니까?

Mermaid는 다이어그램이 다음과 같은 경우에 특히 유용합니다.

  • 는 버전 관리 문서에 속합니다.
  • 코드 또는 절차에 따른 변경;
  • 에는 의미 있는 풀 요청 차이가 필요합니다.
  • 은 표준 모양과 관계를 사용합니다.
  • 은 독점 디자인 파일 없이도 편집 가능해야 합니다.
  • 은 밝은 테마와 어두운 테마로 재생성되어야 합니다.

상세한 일러스트레이션, 픽셀까지 완벽한 레이아웃, 자유형 주석 또는 정확한 수동 배치가 필요한 시각적 디자인에는 적합하지 않습니다.이러한 경우 그리기 도구를 사용하고 액세스 가능한 SVG 또는 이미지를 내보내세요.

예 1: 순서도

순서도는 프로세스, 결정 또는 라우팅 규칙을 설명합니다.

```mermaid
flowchart TD
  A[Choose a DOCX file] --> B{File valid?}
  B -->|Yes| C[Convert to Markdown]
  B -->|No| D[Show an error]
  C --> E[Review the output]
  E --> F[Copy or download]
```

주요 구문:

  • TD 은 위에서 아래로를 의미합니다.
  • LR 는 왼쪽에서 오른쪽으로를 의미합니다.
  • [Text] 은 직사각형 프로세스 노드를 생성합니다.
  • {Text} 는 결정 노드를 생성합니다.
  • --> 는 방향 연결을 생성합니다.
  • -->|Label| 은 연결에 텍스트를 추가합니다.

다음과 같은 안정적이고 짧은 노드 ID를 사용하십시오. A or validate.눈에 보이는 레이블을 괄호 안에 유지하여 문구를 변경하더라도 모든 연결을 변경할 필요는 없습니다.

하위 그래프 추가

하위 그래프 그룹 관련 단계:

```mermaid
flowchart LR
  subgraph Browser
    Upload[Choose file] --> Convert[Convert locally]
  end

  subgraph Output
    Preview[Preview Markdown] --> Save[Download file]
  end

  Convert --> Preview
```

그룹이 소유권, 시스템 경계 또는 단계를 전달할 때 하위 그래프를 사용합니다.단지 장식용으로 상자를 추가하지 마십시오.

예 2: 시퀀스 다이어그램

시퀀스 다이어그램은 상호 작용을 시간 순서로 보여줍니다.API 호출, 인증, 브라우저 워크플로 및 이벤트 기반 시스템에 적합합니다.

```mermaid
sequenceDiagram
  autonumber
  actor User
  participant Browser
  participant Converter

  User->>Browser: Select DOCX file
  Browser->>Converter: Pass local file data
  Converter-->>Browser: Return Markdown
  Browser-->>User: Show editable preview
```

일반 화살표:

  • ->> 는 확실한 메시지를 보냅니다.
  • -->> 은 점선 응답을 보냅니다.
  • participant 는 시스템 또는 서비스를 선언합니다.
  • actor 은 인간 또는 외부 역할을 선언합니다.
  • autonumber 는 상호작용을 순서대로 표시합니다.

하나의 시나리오에 집중하세요.모든 대안과 모든 내부 기능을 보여주려고 시도하는 시퀀스 다이어그램은 코드보다 이해하기가 더 어렵습니다.

대체 경로 표시

```mermaid
sequenceDiagram
  participant Client
  participant API

  Client->>API: POST /documents
  alt Valid request
    API-->>Client: 201 Created
  else Invalid request
    API-->>Client: 400 Bad Request
  end
```

사용 alt, else및 end 은 의미 있는 분기입니다.해당 지점에 여러 페이지의 설명이 필요한 경우 다이어그램 아래에 산문 링크를 연결하세요.

예제 3: 클래스 다이어그램

클래스 다이어그램은 유형, 속성, 작업, 상속 및 관계를 설명합니다.

```mermaid
classDiagram
  class Document {
    +String name
    +String content
    +convert()
  }

  class MarkdownDocument {
    +String frontmatter
    +render()
  }

  Document <|-- MarkdownDocument
```

이 예에서는 다음과 같이 명시합니다. MarkdownDocument 은 다음에서 상속됩니다. Document.완전한 API 참조 문서를 자동으로 대체하는 것이 아니라 개념적 모델을 위한 클래스 다이어그램을 사용하십시오.

좋은 클래스 다이어그램은 독자가 디자인을 이해하는 데 도움이 되지 않는 세부 사항을 생략합니다.모든 비공개 필드를 표시하면 다이어그램을 검색하기 어려운 버전의 소스 코드로 바꿀 수 있습니다.

예 4: 간트 차트

간트 차트는 시간에 따른 작업을 보여줍니다.릴리스 계획, 마이그레이션 및 문서화 프로젝트에 유용합니다.

```mermaid
gantt
  title Documentation migration
  dateFormat YYYY-MM-DD

  section Preparation
  Inventory content :done, inventory, 2026-11-03, 3d
  Define templates  :done, templates, after inventory, 2d

  section Migration
  Convert documents :active, convert, 2026-11-08, 7d
  Editorial review  :review, after convert, 5d

  section Publish
  Final validation  :validate, after review, 2d
```

날짜를 명시적으로 유지하고 한 작업이 다른 작업에 종속되는 경우 작업 ID를 사용하십시오.문서에 저장된 다이어그램은 실제 프로젝트 일정이 변경되어도 자동으로 업데이트되지 않는다는 점을 기억하세요.최신 상태로 유지하려면 소유권을 할당하세요.

예 5: 마인드 맵

마인드맵은 중심 주제를 중심으로 아이디어를 정리합니다.

```mermaid
mindmap
  root((Markdown quality))
    Structure
      Headings
      Lists
      Tables
    Accessibility
      Alt text
      Link text
      Reading order
    Publishing
      GitHub
      Obsidian
      Documentation site
```

마인드 맵은 계획 중에 또는 높은 수준의 개요로 가장 효과적입니다.트리 구조는 실제 개념이 겹치는 계층 구조를 암시할 수 있으므로 정확한 관계에는 덜 유용합니다.

예 6: 엔터티-관계 다이어그램

ER 다이어그램은 데이터 엔터티와 해당 관계를 설명합니다.

```mermaid
erDiagram
  AUTHOR ||--o{ DOCUMENT : writes
  DOCUMENT ||--o{ REVISION : contains
  DOCUMENT }o--o{ TAG : uses

  AUTHOR {
    string id
    string name
  }

  DOCUMENT {
    string id
    string title
    datetime published_at
  }
```

ER 다이어그램을 사용하여 모델을 설명하고 스키마 또는 마이그레이션 파일을 사용하여 구현을 정의합니다.다이어그램에서는 현재 설명과 관련이 없는 인덱스, 제약 조건 및 필드가 생략될 수 있습니다.

미리보기 Mermaid 게시 전

긴 Markdown 문서에 다이어그램을 직접 작성하면 구문 오류를 격리하기가 어렵습니다.집중된 미리보기 루프가 더 빠릅니다.

  1. 열어요 Mermaid 다이어그램 미리보기.
  2. 외부 코드 펜스 없이 다이어그램 정의만 붙여넣습니다.
  3. 다이어그램을 렌더링합니다.
  4. 구문 오류를 읽고 참조된 영역을 수정하십시오.
  5. 생성된 울타리 Markdown를 복사합니다.
  6. 대상에 정적 자산이 필요한 경우 SVG를 다운로드하세요.
  7. 실제 플랫폼에서 최종 Markdown를 테스트합니다.

미리보기는 엄격한 보안 구성으로 브라우저에서 렌더링됩니다.다른 Mermaid 설치에서 허용하더라도 다이어그램 콜백 및 기타 대화형 동작이 비활성화될 수 있습니다.이러한 보수적인 동작은 일반 미리 보기 도구에 적합합니다.

일반적인 Mermaid 오류

다이어그램 유형이 누락되었습니다.

잘못된:

A --> B

맞아요

flowchart LR
  A --> B

첫 번째 줄은 다이어그램 문법을 식별합니다.

레이블의 구두점으로 인해 구문 분석이 중단됩니다.

복잡한 라벨 인용:

flowchart LR
  A["Parse input: DOCX, HTML, or text"] --> B["Create Markdown"]

이는 구문과 유사한 괄호, 구두점 및 레이블에 특히 유용합니다.

예약된 Word이 예기치 않게 사용되었습니다.

Mermaid 문법에는 키워드가 있습니다.공식 순서도 문서에서는 소문자를 구체적으로 경고합니다. end 는 순서도를 깨뜨릴 수 있습니다.대문자로 표기하거나 인용된 노드 라벨 안에 보이는 텍스트를 넣으세요.

flowchart LR
  Start --> Finish["End"]

코드 펜스가 잘못되었습니다.

언어 식별자는 여는 백틱 바로 뒤에 속합니다.

```mermaid
flowchart LR
  A --> B
```

주변 Markdown 구문에서 요구하지 않는 한 전체 울타리를 들여쓰지 마십시오.

한 플랫폼에서는 작동하지만 다른 플랫폼에서는 작동하지 않습니다.

Mermaid가 발전하고 플랫폼은 다양한 렌더러, 버전, 보안 설정 및 활성화된 다이어그램 유형을 사용할 수 있습니다.최신 Mermaid 릴리스에서 지원되는 구문 기능은 다른 구현이나 이전 버전을 사용하는 플랫폼에서 실패할 수 있습니다.

플랫폼 간에 이동하는 문서에 대해 널리 지원되는 구문을 선호합니다.필요한 모든 대상에서 고급 셰이프, 테마, 지시문 및 최신 다이어그램 유형을 테스트하세요.

플랫폼 호환성

호환성을 가정하기보다는 테스트해야 합니다.

플랫폼현재 문서화된 접근 방식중요 참고 사항
GitHub울타리를 사용하세요. mermaid blockGitHub Markdown 파일, 이슈, 토론, 끌어오기 요청 및 Wiki에서 렌더링되는 문서
GitLabGitLab Flavored Markdown에서 Mermaid 코드 블록을 사용합니다.GitLab은 지원되는 Mermaid 버전을 문서화합니다.자체 관리형 설치는 다를 수 있음
Obsidian울타리를 사용하세요. mermaid 메모의 블록Obsidian의 렌더러 및 지원 기능은 릴리스 간에 변경될 수 있습니다.
MkDocs용 재료Mermaid 사용자 정의 펜스 구성기본 테마 통합에는 문서화가 필요합니다. pymdownx.superfences configuration
일반 Markdown 파서종종 코드만 표시됨Mermaid 렌더링에는 일반적으로 JavaScript 통합 또는 빌드 플러그인이 필요합니다.

새로운 기능을 사용하기 전에 현재 공식 문서를 확인하세요.

귀하가 관리하는 문서 사이트의 경우 Mermaid 종속성 버전을 고정하고 업그레이드를 테스트하십시오.그렇지 않으면 사소한 구문 변경으로 인해 전체 사이트의 다이어그램이 변경될 수 있습니다.

Mermaid 및 접근성

렌더링된 SVG는 모든 독자에게 그 의미를 자동으로 전달하지 않습니다.다이어그램을 시각적 요약으로 취급하고 인근 산문에서 동등한 설명을 제공합니다.

이전 변환 흐름도의 경우 다음과 같은 텍스트를 추가합니다.

사용자가 DOCX 파일을 선택합니다.유효한 파일은 로컬로 변환되어 검토를 위해 표시됩니다.유효하지 않은 파일은 오류를 생성합니다.그런 다음 사용자는 검토된 Markdown를 복사하거나 다운로드할 수 있습니다.

접근성 관행:

  • 다이어그램이 설명하는 내용을 소개합니다.
  • 은 복잡한 다이어그램 이후의 결론을 요약합니다.
  • 는 색상만으로 의미를 인코딩하지 않습니다.
  • 내부 약어 대신 읽을 수 있는 라벨을 사용합니다.
  • 밝은 테마와 어두운 테마에서 충분한 대비를 유지합니다.
  • 정확한 마우스 상호작용이 필요한 다이어그램은 피하세요.
  • 필수 정보에 대한 대체 텍스트 또는 표를 제공합니다.
  • 정적 파일에 액세스 가능한 이름이 있어야 하는 경우 SVG를 주의해서 내보내세요.

소스 코드는 작성자에게 유용하지만 독자에게 반드시 좋은 텍스트 대안은 아닙니다.

읽기 쉬운 다이어그램 디자인

다이어그램당 하나의 목적을 유지하세요.

다이어그램은 "요청이 실패한 후 어떻게 되나요?"와 같은 질문에 답해야 합니다.또는 "각 데이터 저장소를 소유하는 서비스는 무엇입니까?"전체 시스템을 설명하려고 하면 분할하세요.

짧은 라벨을 선호합니다.

자세한 설명은 산문으로 작성하세요.긴 레이블은 모바일 화면에서 좁은 노드, 어색한 줄 바꿈 및 큰 다이어그램을 강제합니다.

의도적으로 방향을 사용합니다.

왼쪽에서 오른쪽 흐름은 짧은 프로세스 및 요청 경로에 적합합니다.위에서 아래로의 흐름은 좁은 화면에 더 잘 맞는 경우가 많습니다.커밋하기 전에 둘 다 미리 봅니다.

시각적 스타일 제한

사용자 정의 색상이 어두운 모드 또는 플랫폼 테마와 충돌할 수 있습니다.렌더러의 기본값으로 시작합니다.의미를 전달하고 모든 필수 테마에서 읽을 수 있는 경우에만 스타일을 추가하세요.

소스를 설명 가까이에 두세요.

가능하면 Mermaid 블록을 동일한 Markdown 파일에 저장하십시오.그러면 한 번의 리뷰에서 산문과 다이어그램이 함께 변경됩니다.

Mermaid 대 정적 이미지

다음과 같은 경우 Mermaid를 선택합니다.

  • 다이어그램이 자주 변경됩니다.
  • 소스 차이점은 가치가 있습니다.
  • 레이아웃은 표준 다이어그램 유형을 사용합니다.
  • 게시 플랫폼은 Mermaid를 안정적으로 렌더링합니다.

다음과 같은 경우 SVG 또는 PNG를 선택하십시오.

  • 디자인에는 정확한 수동 레이아웃이 필요합니다.
  • 대상이 Mermaid를 렌더링하지 않습니다.
  • 정확한 모양은 고정된 상태로 유지되어야 합니다.
  • 외부 공유에는 독립형 자산이 필요합니다.

유용한 하이브리드는 Mermaid 소스를 유지하고 이를 렌더링할 수 없는 대상에 대해 SVG를 내보내는 것입니다.내보낸 자산 옆에 소스를 유지하고 재생성 방법을 문서화합니다.

사용 Markdown을 이미지로 를 사용하거나 다음에서 직접 SVG를 다운로드하세요. Mermaid 다이어그램 미리보기 다이어그램 자체가 자산인 경우.

FAQ

Mermaid은 표준 Markdown의 일부입니까?

번호 A 울타리 mermaid 블록은 호환되는 애플리케이션 및 빌드 시스템에서 인식되는 확장입니다.기본 Markdown 파서는 이를 일반 코드로 렌더링할 수 있습니다.

GitHub는 Mermaid 다이어그램을 렌더링합니까?

그렇습니다.GitHub의 문서에서는 Markdown 파일의 Mermaid 렌더링과 여러 공동 작업 영역에 대해 설명합니다.GitHub가 배포된 렌더러와 보안 설정을 제어하므로 최신 구문을 테스트하세요.

Obsidian에서 Mermaid를 사용할 수 있나요?

Obsidian의 공식 도움말에는 Mermaid 스타일의 울타리 다이어그램 블록이 메모로 기록되어 있습니다.기능 지원은 애플리케이션의 렌더러에 따라 변경될 수 있으므로 설치된 버전에서 복잡하거나 새로 도입된 다이어그램 유형을 확인하세요.

Mermaid가 아키텍처 문서를 대체할 수 있습니까?

아니요. 다이어그램은 시스템의 한 보기입니다.이를 의사 결정, 소유권, 제약 조건, 실패 동작 및 신뢰할 수 있는 인터페이스 또는 스키마에 대한 링크와 결합합니다.

어두운 모드에서 다이어그램이 다르게 렌더링되는 이유는 무엇입니까?

플랫폼은 다양한 Mermaid 테마, CSS 변수, 글꼴 및 배경을 적용할 수 있습니다.두 테마를 모두 테스트할 때까지 하드 코딩된 색상을 사용하지 마세요.

내보낸 SVG 파일을 커밋해야 합니까?

게시 대상에 정적 자산이 필요하거나 렌더링된 결과가 안정적으로 유지되어야 하는 경우 SVG를 커밋합니다.또한 두 버전이 표류하는 것을 방지하기 위해 Mermaid 소스와 문서화된 재생 프로세스를 보관하세요.

Mermaid은 기밀 다이어그램에 안전합니까?

기밀성은 편집자 및 출판 작업 흐름에 따라 다릅니다.WordToMD의 미리보기는 브라우저에서 다이어그램을 렌더링하지만 Markdown 또는 SVG를 저장소나 사이트에 게시하는 것은 해당 대상의 액세스 제어를 따릅니다.

결론

Mermaid는 소스가 Markdown와 함께 있기 때문에 다이어그램을 유지 관리할 수 있게 만듭니다.작은 울타리 블록으로 시작하여 질문과 일치하는 다이어그램 유형을 선택하고 구문을 미리 본 후 최종 렌더러에서 테스트합니다.산문을 사용하여 본질적인 의미를 설명하고 대상에 정적 자산이 필요한 경우 SVG를 내보냅니다.

다음의 예제를 시도해 보십시오. Mermaid 다이어그램 미리보기, 주변 문서를 편집하십시오. Markdown 편집자, 향후 기여자가 전체 페이지를 다시 그리지 않고도 다이어그램을 이해하고 업데이트할 수 있도록 다이어그램의 초점을 유지하세요.