mdbook-mermaid

Mermaid 코드 블록 자동 렌더링

마크다운에서 “`mermaid … “` 형태의 코드 블록을 만나면 빌드 시 이를 시각적인 다이어그램으로 변환해 출력본에 자동으로 포함시킵니다.

다양한 다이어그램 유형 지원

흐름도, 시퀀스 다이어그램, Gantt 차트 등 Mermaid가 제공하는 다양한 다이어그램 유형을 그대로 사용할 수 있습니다.

책 설정 자동 구성

`mdbook-mermaid install` 명령을 실행하면 book.toml에 [preprocessor.mermaid] 항목과 output.html.additional-js가 자동으로 추가되며, mermaid.min.js와 mermaid-init.js 파일이 책 디렉터리로 복사됩니다. 이미 설정이 적용된 경우에는 중복 변경 없이 기존 구성을 감지해 그대로 유지합니다.

Mermaid 클라이언트 설정 커스터마이즈

복사된 mermaid-init.js를 직접 수정해 Mermaid의 테마, 시작 옵션, 보안 설정 등 클라이언트 구성 값을 원하는 형태로 조정할 수 있습니다.

설치·시작·기본 사용

설치 후 책에 처음 적용할 때는 다음 명령으로 설정 파일과 필요한 정적 자산을 책 디렉터리에 자동으로 채웁니다.

• 소스로부터 설치: `cargo install mdbook-mermaid` 명령으로 Rust 소스를 빌드해 바이너리를 생성합니다.
• cargo-binstall 사용: cargo-binstall이 이미 설치되어 있다면 `cargo binstall mdbook-mermaid`로 미리 빌드된 바이너리를 내려받을 수 있습니다.
• 수동 설치: GitHub Releases 페이지에서 시스템에 맞는 ZIP 패키지를 내려받아 압축을 풀고, `mdbook-mermaid` 실행 파일을 $HOME/.cargo/bin 경로에 둡니다.
• winget 사용: Windows에서는 `winget install –id badboy.mdbook-mermaid –exact` 명령으로 설치할 수 있습니다.

설치 후 `mdbook-mermaid install path/to/your/book`을 실행하면 book.toml에 [preprocessor.mermaid] 항목과 output.html.additional-js가 추가되고, mermaid.min.js와 mermaid-init.js가 책 폴더로 복사됩니다. 모든 준비가 끝나면 평소처럼 `mdbook path/to/book`을 호출해 책을 빌드합니다. 마크다운 안의 “`mermaid … “` 블록이 자동으로 다이어그램 이미지로 변환됩니다.

활용 예시

• Rust, API, 라이브러리 등 기술 레퍼런스 책에서 함수 흐름이나 호출 관계를 흐름도 다이어그램으로 설명할 때.
• 릴리스 노트나 변경 로그 형식의 책에서 일정과 작업을 Gantt 차트로 표현할 때.
• 시스템 동작 절차를 시퀀스 다이어그램으로 그려, 코드와 함께 한 페이지에 정리할 때.

버전·업데이트

번들된 mermaid.min.js는 수동으로 갱신합니다. 먼저 Mermaid 공식 릴리스 페이지에서 최신 버전을 확인한 다음 저장소 안에서 `cargo xtask ` 명령을 실행하면 minified된 mermaid.js가 자동으로 가져와져 커밋됩니다.

제한·라이선스·확인사항

mdbook-mermaid 자체는 MPL-2.0 라이선스로 배포되며, 2018년부터 2024년까지 Jan-Erik Rediger가 저작권을 보유합니다. 함께 번들된 자산인 mermaid.min.js는 Mermaid의 MIT 라이선스를 따릅니다. 책 작성에 활용할 때에는 책 배포 형태에 맞춰 두 라이선스의 의무 사항을 함께 검토해야 합니다.