virus-warnning / quick-mmd

v1.0.0 2026-10-30 17:28 UTC

Requires (Dev)

• mediawiki/mediawiki-codesniffer: ^52.0
• mediawiki/mediawiki-phan-config: ^0.14
• phpunit/phpunit: ^9.6

MIT

• Raymond Wu

Published on Packagist.org on 2026-11-02 03:50 UTC

README

Parser hook extension for MediaWiki that renders Mermaid diagrams as SVG.

Requirements

Runtime

• PHP >= 8.3.36
• MediaWiki >= 1.43
• One of the following SVG engines:
  • pele (default) — requires Node.js + pele package
  • mmdc — mermaid-cli
  • kroki — Kroki API server

Development

• PHP >= 8.3.36
• ast extension (for Phan)
• Composer
• Docker (for Kroki integration testing)

Installation

Add to your MediaWiki root composer.local.json:

{
    "require": {
        "virus-warnning/quick-mmd": "^1.0"
    }
}

Then run:

composer update

Configuration

Add to LocalSettings.php:

# SVG 生成引擎: pele | mmdc | kroki (default: pele)
$wgQuickMMDEngine = 'pele';

# Kroki API URL (only when engine is 'kroki')
$wgQuickMMDApiUrl = 'http://kroki:8000';

Engine Options

Engine	Description
pele	Node.js-based, uses the pele rendering library. Requires node and a globally installed pele package at /usr/lib/node_modules/pele.
mmdc	Uses mermaid-cli. Requires the mmdc binary in $PATH.
kroki	Sends Mermaid syntax to a Kroki API server. Requires a running Kroki instance.

Usage

In any MediaWiki page, use the <quickmmd> parser hook:

<quickmmd theme="default" name="mychart">
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[Other]
</quickmmd>

Attributes

Attribute	Required	Default	Description
theme	No	default	Mermaid theme (e.g. default, dark, forest, neutral)
name	No	—	Chart name (2–25 chars) used for the SVG cache file name

File Structure

|-- extension.json              # 📋 MediaWiki extension registration
|-- composer.json               # 📦 Composer dependencies
|-- phpcs.xml                   # ✅ PHPCS config (MediaWiki standard)
|-- phpunit.xml                 # 🧪 PHPUnit config
|-- config-puppeteer.json       # 🤖 Puppeteer config (for mmdc)
|-- LICENSE                     # 📄 MIT License
|-- .phan/
|   |-- config.php              # 🔍 Phan static analysis config
|-- src/
|   |-- ExtensionConstants.php  # 🏷️ Extension name, version constants
|   |-- Hook.php                # 🪝 MediaWiki hook registration & main logic
|   |-- Command.php             # 🖥️ Shell command execution (ShellBox)
|   |-- FieldResult.php         # 📝 Form field result wrapper
|   |-- FileSystemUtils.php     # 📁 File system utilities
|   |-- Validator.php           # ✔️ MMD syntax validation
|   |-- pele-cli.js             # 🟢 Node.js script for pele rendering
|-- templates/
|   |-- mmd-builder.php         # 🏗️ mmdc execution template (stdin -> SVG)
|-- i18n/
|   |-- en.json                 # 🇬🇧 English translations
|   |-- zh-hant.json            # 🇹🇼 Traditional Chinese translations
|   |-- ja.json                 # 🇯🇵 Japanese translations
|-- tests/
|   |-- bootstrap.php           # 🚀 Test bootstrap (stubs MW globals)
|   |-- FieldResultTest.php     # 🧪 FieldResult unit tests
|   |-- FileSystemUtilsTest.php # 🧪 FileSystemUtils unit tests
|   |-- ValidatorTest.php       # 🧪 Validator unit tests
|-- debug/                      # 🐛 Debug files (not in VCS)

Development

Run Tests

composer test

Code Style

# Check
composer phpcs

# Auto-fix
composer phpcbf

Static Analysis

composer phan

License

MIT