단일 HTML 파일에서 Mermaid 사용

Mermaid는 텍스트 줄을 다이어그램으로 바꾸는 JavaScript 라이브러리입니다. 하나의 사전 요소와 하나의 모듈 스크립트는 모두 페이지에 필요합니다.

영문 원문 보기

Mermaid는 텍스트에서 순서도, 시퀀스 다이어그램, 간트 차트, 클래스 다이어그램 등의 다이어그램을 그리는 오픈 소스 JavaScript 라이브러리입니다. HTML에서는 <pre class="mermaid">에 다이어그램 텍스트를 넣고 하나의 모듈 스크립트를 추가합니다.

설치할 것도 없고 빌드 단계도 없습니다.

다음은 가장 작은 작업 페이지입니다. 아래 순서도는 몇 줄의 텍스트입니다.

실행 예제직접 써 보고 코드를 복사하세요
링크로 공유하기
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Mermaid in one HTML file</title>
<style>
  body { margin: 0; padding: 16px; font-family: system-ui, sans-serif; background: #fff; }
  .mermaid { margin: 0; text-align: center; }
</style>
</head>
<body>

<!-- The diagram is plain text. Mermaid replaces it with an SVG. -->
<pre class="mermaid">
flowchart TD
  A[Write the diagram as text] --> B{Does it render?}
  B -->|Yes| C[Share the page]
  B -->|No| D[Check the syntax]
  D --> A
</pre>

<!-- type="module" is required for import. Pin the exact version. -->
<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@12.0.0/dist/mermaid.esm.min.mjs';
  mermaid.initialize({ startOnLoad: true });
</script>
</body>
</html>
전체 페이지: 하나의 사전 요소와 하나의 모듈 스크립트. 텍스트를 편집하면 다이어그램이 다시 그려집니다.

복사할 준비가 된 중요한 두 부분:

<pre class="mermaid">
flowchart TD
  A[Write the diagram as text] --> B{Does it render?}
  B -->|Yes| C[Share the page]
  B -->|No| D[Check the syntax]
</pre>

<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@12.0.0/dist/mermaid.esm.min.mjs';
  mermaid.initialize({ startOnLoad: true });
</script>

머메이드(Mermaid)는 MIT 라이선스로 출시됩니다. npm 및 jsDelivr의 현재 버전은 12.0.0입니다.

페이지에서 텍스트를 다이어그램으로 바꾸는 방법

스크립트가 실행될 때까지 브라우저는 <pre>를 일반 텍스트로 표시합니다. 페이지가 로드되면 Mermaid는 class="mermaid"가 있는 모든 요소를 ​​찾아 해당 텍스트를 읽고 이를 SVG 그림으로 바꿉니다.

텍스트는 HTML에 유지됩니다. Mermaid는 페이지가 로드된 후 이를 SVG로 교체합니다.
텍스트는 HTML에 유지됩니다. Mermaid는 페이지가 로드된 후 이를 SVG로 교체합니다.
  • **flowchart TD**는 유형과 방향을 설정합니다. TD는 하향식이고 LR은 왼쪽에서 오른쪽입니다.
  • **A[text]**는 상자이고, B{text}는 결정 다이아몬드이며, C(text)는 둥근 모서리를 갖습니다.
  • **-->**는 화살표입니다. -->|Yes|로 라벨을 붙이세요.

결과는 일반 페이지의 SVG이므로 확대/축소 시 크기가 조정되고 선명하게 유지됩니다. 라이브러리 없이 상자와 화살표를 직접 그리려면 HTML, CSS 및 SVG의 순서도를 참조하세요.

스크립트는 type="module"이어야 합니다.

코드는 ES 모듈인 mermaid.esm.min.mjs를 가져옵니다. import 문은 모듈 스크립트에서만 작동합니다. 일반 <script>에서 브라우저는 SyntaxError를 발생시키고 아무 것도 렌더링하지 않으며 페이지에는 여전히 원시 텍스트가 표시됩니다.

type="module"이 없으면 가져오기 행은 구문 오류이며 다이어그램은 텍스트로 유지됩니다.
type="module"이 없으면 가져오기 행은 구문 오류이며 다이어그램은 텍스트로 유지됩니다.

두 가지 관련 세부정보:

  • 모듈 스크립트는 HTML이 구문 분석될 때까지 기다리므로 헤드나 본문에 배치될 수 있습니다.
  • 모듈 내부에 선언된 변수는 전역 변수가 아닙니다. 별도의 클래식 스크립트에 있는 코드는 mermaid를 볼 수 없으므로 Mermaid 호출을 동일한 모듈에 유지하세요.

주소에 버전 고정

주소에 따라 어떤 릴리스를 받을지 결정됩니다. jsDelivr은 mermaid@12를 범위로 취급하고 최신 12.x 릴리스를 제공합니다. mermaid@12.0.0는 변경되지 않는 하나의 정확한 파일입니다.

주소 무엇을로드합니까? 다음 용도로 사용하세요.
mermaid@12.0.0 정확히 12.0.0 공유하거나 보관하는 페이지
mermaid@12 최신 12.x 빠른 실험
mermaid(버전 없음) 최신 릴리스 실제 페이지에는 권장되지 않습니다.

주요 릴리스에서는 다이어그램의 모양이 변경되기 때문에 이는 중요합니다. 버전 12.0.0에서는 redux-color를 기본 테마로, neo를 기본 모양으로 만들었으며 이제 dagre 대신 ELK를 사용하여 다이어그램을 레이아웃합니다. 고정 해제된 버전을 로드하는 페이지는 다음 달에는 다르게 보일 수 있습니다.

버전 12의 이전 모습을 유지하기 위해 릴리스 노트에서는 다음 설정을 제공합니다.

mermaid.initialize({ layout: 'dagre', theme: 'default', look: 'classic' });

HTML 파서가 가장 먼저 사용하는 문자

<pre> 내부의 텍스트는 Mermaid가 보기 전에 HTML로 구문 분석됩니다. < 뒤에 문자가 오면 태그가 시작됩니다. 아래 예에서 브라우저는 <b] -->를 요소로 읽으므로 Mermaid는 깨진 텍스트를 수신하고 "텍스트의 구문 오류"를 표시합니다.

pre의 원시 <는 태그가 됩니다. Mermaid의 코드 #lt;는 HTML 파서에서 살아남습니다.
pre의 원시 <는 태그가 됩니다. Mermaid의 코드 #lt;는 HTML 파서에서 살아남습니다.

&lt;를 작성하는 것은 완전히 도움이 되지 않습니다. 브라우저는 이를 <로 다시 변환하고 레이블은 잘립니다. 테스트에서 효과가 있었던 것은 & 대신 #로 작성된 Mermaid의 자체 엔터티 코드입니다.

flowchart LR
  A[a #lt; b] --> C[c]

동일한 엔터티 코드에는 따옴표(#quot;) 및 기타 어색한 문자가 포함됩니다. 일반적인 HTML 측면에 대해서는 HTML 엔터티를 참조하세요.

주의할 단어가 하나 더 있습니다. 노드 이름으로 소문자 end가 있으면 순서도가 중단됩니다. 대신 End 또는 END를 작성하세요.

JavaScript로 작성한 텍스트에서 다이어그램 그리기

startOnLoad는 페이지가 로드될 때 이미 페이지에 있는 요소만 처리합니다. 텍스트 상자, 가져오기 결과 또는 템플릿에서 그리려면 이를 끄고 mermaid.render를 직접 호출하세요.

실행 예제직접 써 보고 코드를 복사하세요
링크로 공유하기
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Mermaid live editor</title>
<style>
  body { margin: 0; padding: 14px; font-family: system-ui, sans-serif; background: #f6f7f9; color: #1d2330; }
  label { font-weight: 600; font-size: 14px; }
  textarea {
    display: block; width: 100%; box-sizing: border-box; height: 150px; margin: 6px 0 8px;
    font: 14px/1.4 ui-monospace, Consolas, monospace; padding: 8px; border: 1px solid #cdd3dc; border-radius: 8px;
  }
  #status { font-size: 13px; min-height: 18px; color: #0f5132; }
  #status.error { color: #9a3412; }
  #out { background: #fff; border: 1px solid #e1e4ea; border-radius: 10px; padding: 10px; margin-top: 8px; text-align: center; overflow-x: auto; }
</style>
</head>
<body>
<label for="src">Diagram text (edit it)</label>
<textarea id="src" spellcheck="false">sequenceDiagram
  Browser->>CDN: import mermaid
  CDN-->>Browser: library code
  Browser->>Browser: text becomes SVG</textarea>
<div id="status"></div>
<div id="out"></div>

<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@12.0.0/dist/mermaid.esm.min.mjs';
  mermaid.initialize({ startOnLoad: false });  // we render ourselves

  const src = document.getElementById('src');
  const out = document.getElementById('out');
  const status = document.getElementById('status');
  let count = 0, timer;

  async function draw() {
    try {
      await mermaid.parse(src.value);               // throws on bad syntax
      const { svg } = await mermaid.render('d' + (++count), src.value);
      out.innerHTML = svg;
      status.className = '';
      status.textContent = 'Rendered.';
    } catch (err) {
      status.className = 'error';                    // keep the last good diagram
      status.textContent = 'Syntax error: ' + String(err.message || err).split('\n')[0];
    }
  }

  src.addEventListener('input', () => { clearTimeout(timer); timer = setTimeout(draw, 400); });
  draw();
</script>
</body>
</html>
상자에 입력하세요. 잠시 후에 유효한 텍스트가 그려지며 구문 오류로 인해 마지막으로 좋은 다이어그램이 유지됩니다.

그것의 핵심:

mermaid.initialize({ startOnLoad: false });

await mermaid.parse(text);  // throws on bad syntax
const { svg } = await mermaid.render('diagram1', text);
out.innerHTML = svg;
  • mermaid.parse 텍스트를 그리지 않고 확인하고 잘못된 구문이 발생합니다. try/catch는 메시지를 표시할 수 있습니다.
  • **mermaid.render**는 ID와 텍스트를 가져와서 svg 속성이 SVG 코드인 객체를 반환합니다.
  • 각 렌더링에 새 ID를 부여하세요. 데모에서는 d1, d2 등이 계산됩니다.

테마를 정하고, 같은 다이어그램을 다시 그려요

initialize를 사용하여 전체 페이지에 대한 테마를 선택하거나 텍스트 상단에 구성 블록이 있는 하나의 다이어그램에 대한 테마를 선택하세요. 버전 12에는 default, neutral, dark, forest 및 base 중 11개의 테마가 나열되어 있습니다.

실행 예제직접 써 보고 코드를 복사하세요
링크로 공유하기
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Mermaid diagrams with a theme switch</title>
<style>
  body { margin: 0; padding: 14px; font-family: system-ui, sans-serif; background: #fff; color: #1d2330; }
  .bar { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; margin-bottom: 10px; }
  select { font: inherit; padding: 4px 6px; }
  .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(240px, 1fr)); gap: 12px; }
  .card { border: 1px solid #e1e4ea; border-radius: 10px; padding: 8px; overflow-x: auto; }
  h2 { font-size: 14px; margin: 0 0 6px; }
  .mermaid { margin: 0; text-align: center; }
  body.dark { background: #1f2020; color: #e5e7eb; }  /* page follows the dark theme */
  body.dark .card { border-color: #3a3d42; }
</style>
</head>
<body>
<div class="bar">
  <label for="theme"><b>Theme</b></label>
  <select id="theme">
    <option>redux-color</option><option>default</option><option>neutral</option>
    <option>dark</option><option>forest</option>
  </select>
</div>

<div class="grid">
  <div class="card"><h2>Flowchart</h2>
    <pre class="mermaid">
flowchart TD
  Idea --> Draft --> Review
  Review -->|changes| Draft
  Review -->|ok| Done</pre></div>
  <div class="card"><h2>Pie chart</h2>
    <pre class="mermaid">
pie title Time spent
  "Writing" : 50
  "Review" : 30
  "Fixes" : 20</pre></div>
</div>

<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@12.0.0/dist/mermaid.esm.min.mjs';

  const boxes = [...document.querySelectorAll('.mermaid')];
  const sources = boxes.map((el) => el.textContent);  // keep the text: rendering replaces it

  const select = document.getElementById('theme');

  async function drawAll(theme) {
    select.disabled = true;                            // one render at a time
    mermaid.initialize({ startOnLoad: false, theme });
    document.body.classList.toggle('dark', theme === 'dark');
    boxes.forEach((el, i) => {
      el.removeAttribute('data-processed');            // allow a second render
      el.textContent = sources[i];
    });
    await mermaid.run({ nodes: boxes });
    select.disabled = false;
  }

  select.addEventListener('change', () => drawAll(select.value));
  drawAll(select.value);
</script>
</body>
</html>
테마를 전환하면 저장된 텍스트에서 두 다이어그램이 다시 그려집니다.

다시 그리기 작업을 수행하는 두 가지 사항은 다음과 같습니다.

  1. 원본 텍스트를 유지하세요. 렌더링하면 요소의 내용이 바뀌므로 먼저 텍스트를 저장하세요.
  2. 처리된 표시를 지웁니다. Mermaid는 자신이 그린 각 요소에 data-processed를 추가하고 다음에 건너뜁니다. mermaid.run를 다시 호출하기 전에 해당 속성을 제거하십시오.
el.removeAttribute('data-processed');
el.textContent = savedText;
await mermaid.run({ nodes: [el] });

대신 단일 다이어그램의 테마를 설정하려면 해당 텍스트를 구성 블록으로 시작하세요.

---
config:
  theme: forest
---
flowchart LR
  A --> B

작동하지 않을 때

당신이 보는 것 원인 수정
원시 텍스트가 표시되고 아무것도 그려지지 않습니다. 스크립트는 모듈이 아닙니다. 스크립트 태그에 type="module" 추가
"모듈 외부에서 import 문을 사용할 수 없습니다" 위와 동일 type="module" 추가
"텍스트의 구문 오류" 인어가 다이어그램을 구문 분석할 수 없습니다. 오류 이름 줄을 확인하거나 mermaid.live의 텍스트를 테스트하세요.
< 근처의 구문 오류 HTML 파서는 이를 태그로 읽습니다. 대신 #lt;를 작성하세요.
end라는 노드에서 순서도가 중단됩니다. end는 예약어입니다. End 또는 END 쓰기
다이어그램이 지난달과 다르게 보입니다. 주소에 정확한 버전이 없습니다. 핀 mermaid@12.0.0
나중에 다이어그램을 추가했는데 텍스트로 유지됩니다. startOnLoad는 한 번만 실행됩니다. 추가 후 mermaid.run()를 호출하세요.
두 번째 mermaid.run는 아무 작업도 수행하지 않습니다. 요소에 data-processed가 있습니다. 그것을 제거하고 텍스트를 복원하십시오
노드의 링크를 클릭하면 아무 작업도 수행되지 않습니다. 기본 securityLevel는 엄격합니다. securityLevel를 느슨하게 설정

페이지에 아무것도 표시되지 않고 심지어 텍스트도 표시되지 않으면 문제는 Mermaid 외부에 있는 것입니다. HTML 파일에서 JavaScript가 작동하지 않음에서는 일반적인 점검 사항을 다룹니다.

링크로 공유하세요

인어 다이어그램은 스크립트로 그려집니다. .html 첨부 파일은 전화기에서 일반 코드로 열릴 수 있으며 스크린샷을 편집할 수 없습니다. 보내는 사람에게는 스크립트가 실행되는 페이지가 필요합니다.

작업 버전을 공유하려면 페이지를 NOS 문서에 붙여넣고 공유 링크 만들기를 선택하세요. 링크할 HTML이 이를 안내합니다.

페이지는 작성된 대로 렌더링되고 cdn.jsdelivr.net의 스크립트가 로드되므로 계정이 필요 없이 링크를 여는 모든 사람을 위해 다이어그램이 그려집니다. 나중에 다이어그램 텍스트를 편집하면 동일한 링크에 새 버전이 표시됩니다.

자주 묻는 질문

Mermaid를 사용하려면 npm이나 빌드 단계가 필요합니까?

아니요. type="module"인 스크립트는 jsDelivr CDN에서 Mermaid를 직접 가져올 수 있으며, 페이지가 로드될 때 페이지에서 class="mermaid"인 모든 요소가 그려집니다. npm은 프로젝트에 이미 번들러가 있는 경우에만 필요합니다.

어떤 버전의 Mermaid를 로드해야 합니까?

CDN 주소에 mermaid@12.0.0과 같은 정확한 버전을 고정하세요. @12와 같은 범위는 최신 12.x 릴리스를 따르므로 페이지를 편집하지 않고도 다이어그램의 모양을 변경할 수 있습니다.

내 다이어그램에 "텍스트의 구문 오류"가 표시되는 이유는 무엇입니까?

Mermaid가 수신한 텍스트를 구문 분석할 수 없습니다. HTML 파일의 일반적인 원인은 순서도의 소문자 단어 끝과 Mermaid가 보기 전에 HTML 파서가 태그의 시작으로 읽은 < 문자입니다.

사용자가 입력한 텍스트에서 다이어그램을 어떻게 그리나요?

startOnLoad를 false로 설정하여 mermaid.initialize를 호출한 다음 텍스트를 mermaid.render에 전달합니다. innerHTML을 사용하여 페이지에 삽입한 SVG 코드가 포함된 개체를 반환합니다.

Mermaid 노드에 대한 클릭이 허용됩니까?

기본 설정으로는 그렇지 않습니다. 기본 securityLevel은 엄격하여 클릭 상호작용을 비활성화합니다. securityLevel을 느슨하게 설정하면 활성화됩니다.