アーキテクチャ設計¶
概要¶
MkDocs Mermaid to Image Pluginは、MkDocsプロジェクト内のMermaid図をビルド時に静的画像（PNG/SVG）に変換するプラグインです。Mermaid CLIを利用してMarkdownファイル内のMermaidコードブロックを画像化し、Markdownの内容を画像参照タグに置き換えます。これにより、PDF出力やオフライン環境での閲覧に対応します。
プロジェクト構造¶
mkdocs-mermaid-to-image/
└── src/
└── mkdocs_mermaid_to_image/
├── __init__.py # パッケージ初期化・バージョン情報
├── plugin.py # MkDocsプラグインメインクラス (MermaidToImagePlugin)
├── processor.py # ページ処理の統括 (MermaidProcessor)
├── markdown_processor.py # Markdown解析 (MarkdownProcessor)
├── image_generator.py # 画像生成 (MermaidImageGenerator)
├── mermaid_block.py # Mermaidブロック表現 (MermaidBlock)
├── config.py # 設定スキーマ (MermaidPluginConfig, ConfigManager)
├── types.py # 型定義 (TypedDictなど)
├── exceptions.py # カスタム例外クラス
├── logging_config.py # ロギング設定・構造化フォーマッタ
└── utils.py # ユーティリティ関数
ファイル依存関係図¶
クラス図¶
プラグイン処理フロー¶
1. プラグイン初期化フロー (on_config)¶
2. ファイル処理フロー (on_files)¶
3. ページ処理フロー (on_page_markdown)¶
4. 画像生成フロー (MermaidImageGenerator.generate)¶
環境別処理戦略¶
このプラグインは、mkdocs build（本番ビルド）とmkdocs serve（開発サーバー）で動作を切り替えます。
モード判定¶
# src/mkdocs_mermaid_to_image/plugin.py
class MermaidToImagePlugin(BasePlugin[MermaidPluginConfig]):
def __init__(self) -> None:
# ...
self.is_serve_mode: bool = "serve" in sys.argv
self.is_verbose_mode: bool = "--verbose" in sys.argv or "-v" in sys.argv
プラグイン有効化制御¶
プラグインの有効化は、環境変数設定に基づいて動的に制御できます：
# src/mkdocs_mermaid_to_image/plugin.py
def _should_be_enabled(self, config: MermaidPluginConfig) -> bool:
enabled_if_env = config.get("enabled_if_env")
if enabled_if_env is not None:
# 環境変数の存在と値をチェック
env_value = os.environ.get(enabled_if_env)
return env_value is not None and env_value.strip() != ""
# 通常のenabled設定に従う
return config.get("enabled", True)
ログレベル制御¶
verboseモードの有無に応じてログ出力を調整：
# src/mkdocs_mermaid_to_image/plugin.py
# verboseモードに応じてログレベルを動的に設定
config_dict["log_level"] = "DEBUG" if self.is_verbose_mode else "WARNING"
プラグイン設定管理¶
設定は mkdocs.yml で行われ、src/mkdocs_mermaid_to_image/plugin.py の config_scheme と src/mkdocs_mermaid_to_image/config.py の MermaidPluginConfig で定義されます。
設定スキーマ¶
# src/mkdocs_mermaid_to_image/plugin.py
class MermaidToImagePlugin(BasePlugin[MermaidPluginConfig]):
config_scheme = (
("enabled", config_options.Type(bool, default=True)),
("enabled_if_env", config_options.Optional(config_options.Type(str))),
("output_dir", config_options.Type(str, default="assets/images")),
("image_format", config_options.Choice(["png", "svg"], default="png")),
# ... 他の設定項目 ...
("cleanup_generated_images", config_options.Type(bool, default=False)),
)
設定検証¶
ConfigManager.validate_config() で設定値の整合性を検証します。
ファイル管理戦略¶
生成画像のFiles登録¶
生成された画像をMkDocsのFilesオブジェクトに動的に追加し、ビルド対象に含めます。
# src/mkdocs_mermaid_to_image/plugin.py
def _register_generated_images_to_files(self, image_paths: list[str], docs_dir: Path, config: Any) -> None:
if not (image_paths and self.files):
return
from mkdocs.structure.files import File
for image_path in image_paths:
image_file_path = Path(image_path)
if image_file_path.exists():
rel_path = image_file_path.relative_to(docs_dir)
file_obj = File(str(rel_path), str(docs_dir), str(config["site_dir"]), ...)
self.files.append(file_obj)
画像の配置戦略¶
- 開発時:
docs_dir内のoutput_dirに画像を生成します。 - ビルド時: MkDocsが
_register_generated_images_to_filesで登録された画像を自動的にサイトディレクトリにコピーします。 - クリーンアップ:
cleanup_generated_images設定でビルド後の自動削除が可能です。
エラーハンドリング戦略¶
例外階層¶
エラー発生時の処理¶
- 設定エラー (
MermaidConfigError,MermaidFileError):on_configで発生し、ビルドプロセスを即座に停止させます。 - CLI実行エラー (
MermaidCLIError):image_generator.pyで発生します。 error_on_fail=true: 例外が送出され、ビルドが停止します。error_on_fail=false: エラーログを出力後、処理を継続します（該当図は画像化されません）。- 画像生成エラー (
MermaidImageError): 画像ファイルが生成されなかった場合に発生します。 - その他エラー: 予期せぬエラーは
on_page_markdown内でキャッチされ、error_on_failの設定に従って処理されます。
ログ出力戦略¶
- 設定レベル:
log_level設定で制御します。 - Verboseモード: コマンドライン引数
--verbose/-vで詳細ログ（DEBUGレベル）を有効化します。 - 通常モード:
WARNINGレベルのログのみ出力されます。 - 条件付きログ: 画像生成時は常にINFOレベルで結果を出力します。