Pele
Mermaid 소스를 Pele로 SVG로 렌더링합니다. Pele은 동기식 라이브러리입니다. Puppeteer, mermaid-cli, MCP 서버가 필요 없습니다. 이 스킬의 인터페이스는 scripts/render.mjs입니다.
스킬 루트는 이 파일이 있는 디렉터리입니다. 아래 모든 경로는 해당 디렉터리를 기준으로 합니다. 이 스킬이 Claude Code, Hermes 또는 OpenCode에 설치된 후에도 마찬가지입니다.
사용 시기
- 사용자가 Mermaid 다이어그램을 SVG, HTML 또는 이미지 파일로 원할 때.
.mmd파일이나```mermaid코드 블록을 렌더링하고 확인해야 할 때.- 사용자가 지원되는 32가지 유형 중 하나로 그릴 수 있는 다이어그램을 요청하고, 채팅 코드 블록이 아닌 파일을 원할 때. 여기에는 덜 익숙한 유형인 Wardley 맵, fishbone, Venn, swimlane, radar, treemap, sankey, railroad 문법, file tree, Cynefin, event model도 포함됩니다. 아래 다이어그램 유형을 참조하세요.
다음 경우에는 사용하지 마세요:
- Mermaid 코드 블록이 GitHub, Obsidian 또는 다른 뷰어에서 이미 렌더링되는 Markdown에 남아 있어야 할 때.
- 요청된 결과물이 Mermaid가 아닌 경우 (손으로 그린 Excalidraw JSON, 맞춤형 아키텍처 페이지, 스크린샷 주석).
- 사용자가 mermaid.js와 픽셀 단위로 완전히 일치하는 출력을 필요로 할 때. Pele은 자체 레이아웃을 가지고 있습니다.
이것을 MCP 서버로 감싸지 마세요. 하나의 스크립트 호출로 전체 기능이 수행됩니다.
전제 조건
- Node.js 20 이상,
npm이PATH에 있어야 합니다. - 종속성 설치는 스킬 루트(
package.json이 이 파일 옆에 있음)에서 이루어지며, 사용자 프로젝트에서는 절대 이루어지지 않습니다.
node_modules/pele이 없으면 스크립트가 그곳에서 npm install을 실행합니다. 직접 수행할 수도 있습니다:
npm install --no-fund --no-audit
완료 확인: node scripts/render.mjs --check가 종료 코드 0으로 종료되고 stderr JSON에 "ok": true와 pele 버전이 있어야 합니다.
다이어그램 유형
선택하기 전에 전체 목록을 알아두세요. Pele은 32가지 유형을 렌더링하며, 이 중 1/3은 사용자가 말하는 이름과 다른 -beta 헤더가 필요합니다.
node scripts/render.mjs --types
이 명령은 type, 정확한 첫 줄 header, 용도, 작동하는 example 경로를 JSON으로 출력합니다. references/diagram-types.md에도 동일한 테이블, 실패하는 헤더, 유형 선택 방법이 있습니다.
- 독자가 필요로 하는 것을 보여주는 유형을 선택하세요. 단계별 소유자 →
swimlane. 한 문제의 원인들 →ishikawa. 날짜가 있는 작업 →gantt. 폴더 레이아웃 →treeView. 비례적 흐름 →sankey. - 요청이 어떤 유형에도 맞지 않으면 (자유 형식 레이아웃, 그림, 나열되지 않은 차트 유형), 그렇게 말하고 flowchart에 억지로 맞추지 마세요.
- 사용자가 목록에 없는 특정 다이어그램 유형을 언급하면, 가장 가까운 지원 유형을 제안하기 전에 먼저 그 유형이 없다고 말하세요. 조용히 근사하지 마세요.
절차
--types에서 유형과 정확한 헤더를 선택하세요.-beta유형이거나 구문이 확실하지 않은 유형의 경우, 먼저example파일을 읽고 그 구조를 복사하세요.- Mermaid 소스를
.mmd파일에 작성하세요. 여러 줄 다이어그램을 셸 인수로 전달하지 마세요. - 렌더링하세요:
node scripts/render.mjs INPUT.mmd OUTPUT.svg
- stderr의 JSON 영수증을 읽으세요. 완료 조건: 종료 코드 0,
"ok": true, 영수증의type이 선택한 유형이며, 출력 파일이<svg로 시작해야 합니다. "ok": false인 경우:unsupported-diagram: 첫 줄이 알려진 헤더가 아닙니다.suggest[0].header가 있으면 사용하고, 없으면--types에서 하나 선택하세요.syntax또는semantic:line/column에서snippet을 사용하여 소스를 수정하고, 해당 유형의 예제와 비교한 후 다시 렌더링하세요.- mermaid-cli, 헤드리스 브라우저 또는 수동 SVG로 전환하지 마세요.
- 절대 출력 경로를 보고하세요. 사용자가 마크업을 요청하지 않는 한 SVG를 채팅에 붙여넣지 마세요. 종료 코드가 0이 아닌데 성공을 주장하지 마세요.
사용자가 브라우저에서 열 수 있는 파일을 필요로 할 때 --html 또는 .html로 끝나는 출력 경로를 사용하세요. HTML은 SVG를 인라인으로 포함하고 Pele의 CSS 색상 변수를 설정합니다.
node scripts/render.mjs --html INPUT.mmd OUTPUT.html
영수증
성공 시 stderr:
{"ok":true,"type":"flowchart","width":180,"height":80,"bytes":1200,"output":"/abs/OUTPUT.svg","html":false,"pele":"1.6.0"}
실패 시 stderr, 종료 코드 1 (Pele을 설치할 수 없으면 종료 코드 2):
{"ok":false,"code":"syntax","message":"...","type":"flowchart","line":2,"column":5,"snippet":"..."}
code는 syntax, semantic, unsupported-diagram, limit, usage, install-failed 또는 render-failed입니다. message를 텍스트로 표시하세요. 다이어그램 소스를 포함할 수 있습니다.
unsupported-diagram 영수증에는 hint와 suggest도 있습니다:
{"ok":false,"code":"unsupported-diagram","hint":"첫 줄을 아래 헤더로 교체하세요. 많은 유형에 -beta 접미사가 필요합니다.","suggest":[{"type":"radar","header":"radar-beta","example":"/abs/examples/types/radar.mmd"}]}
플래그
| 플래그 | 용도 |
|---|---|
--check | Pele을 로드하고 버전을 출력하며 렌더링하지 않음 |
--types | 지원되는 유형, 헤더 및 예제 경로를 JSON으로 stdout에 출력 |
--html | 원시 SVG 대신 독립형 HTML |
--fixed | 고정 픽셀 크기. .svg 파일의 기본값 |
--responsive | SVG가 컨테이너에 맞게 축소될 수 있음. stdout 및 HTML의 기본값 |
--max-width <px> | Pele이 레이아웃을 조정하도록 요청. 640px 미만에서 넓은 LR flowchart를 세로로 전환할 수 있음 |
--font-size <px> | 기본 글꼴 크기 |
--font <family> | 레이블 글꼴 |
--id-prefix <str> | 한 페이지에 여러 SVG가 공유될 때 고유 접두사 |
stdout은 SVG(또는 HTML)를 유지합니다. 영수증은 항상 stderr의 마지막 JSON 줄입니다.
주변의 ```mermaid 코드 블록은 제거됩니다. Mermaid 자체 frontmatter는 제거되지 않습니다.
함정
- 파일 SVG의 기본값은
responsive: false입니다. SVG가 임베드되어 축소되어야 할 때만--responsive를 전달하세요. - Node에는 캔버스 측정 도구가 없습니다. 레이블 너비가 브라우저 렌더링과 다를 수 있습니다. 이는 예상된 동작입니다.
- 사용자가 좁은 레이아웃을 요청하지 않는 한
--max-width를 전달하지 마세요. 방향을 변경할 수 있습니다. - 헤더는 정확해야 합니다.
radar,venn,wardley,swimlane,treeView,usecase,cynefin,railroad,agentflow모두-beta가 필요합니다.architecture도-beta가 필요합니다.fishbone헤더는 없습니다.ishikawa-beta를 사용하세요. - 아이콘 이름(
fa:fa-user,cloud,database,disk,internet,server외의 아키텍처 아이콘)은 오류 없이 빈 슬롯으로 렌더링됩니다. 이 스크립트는 아이콘 콜백을 제공하지 않습니다. 아이콘을 삭제하거나 텍스트로 대체하세요. - 소스 제한은 50,000자입니다. 출력 제한은 4,000,000입니다. Flowchart 간선 제한은 5,000입니다.
- 사용자 저장소의
npm install은 이 스크립트를 충족시키지 못합니다. 패키지는 스킬 루트에 있습니다. node_modules가 존재하지만 Pele을 로드하는 데 실패하면, 해당node_modules를 삭제하고 스킬 루트에서npm install을 실행하세요.- 이미 열려 있는 에이전트 세션은 세션 중간에 설치된 스킬을 인식하지 못합니다. 이는 로더 캐시 문제이지 잘못된 설치가 아닙니다.
검증
스킬 루트에서:
npm run smoke
완료 조건: 종료 코드 0, stdout JSON에 "ok": true, pele 버전, "types": 32, 모든 카탈로그 유형이 포함된 rendered 목록, code: "syntax"와 0이 아닌 line이 있는 syntaxError가 있어야 합니다. 또한 scripts/catalog.mjs가 Pele 자체 유형 목록에서 벗어나거나 헤더가 해당 유형으로 감지되지 않으면 smoke가 실패합니다. examples/broken.mmd는 계속 실패해야 합니다. Smoke 통과가 새 다이어그램이 올바르다는 것을 의미하지는 않습니다. 각 새 다이어그램에는 여전히 자체 영수증이 필요합니다.