---
name: md2img
description: >
  This skill should be used when the user wants to render a Markdown document
  (containing Mermaid diagrams, LaTeX math formulas, or rich formatting) into a PNG image. 
---

# md2img

Render Markdown documents into high-quality PNG images with full support for Mermaid diagrams, LaTeX math formulas, code syntax highlighting, and GFM tables.

## Features

- **Mermaid diagrams**: flowchart, sequence, class, state, gantt, pie, etc. (rendered in-browser via mermaid.js)
- **LaTeX math**: inline `$...$` and block `$$...$$` / `\[...\]` (via KaTeX)
- **GFM syntax**: tables, task lists, strikethrough, code blocks
- **Code highlighting**: via highlight.js CSS
- **Dark/Light theme**: override with `--dark` or `--light` flag
- **Paper sizes**: A4 (default) or Letter, 2x DPI for crisp output
- **Cross-platform**: Windows (Chrome/Edge) and Linux (Chrome/Chromium)

## Usage Workflow

1. Write the Markdown content to a temporary `.md` file
2. Run the render script
3. Present the generated PNG to the user

### Command

```bash
node <skill_dir>/scripts/render.js <input.md> [output.png] [--paper=a4|letter] [--dark|--light]
```

### Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `input.md` | (required) | Input Markdown file path |
| `output.png` | `<input>.png` | Output PNG file path |
| `--paper` | `a4` | Paper size: `a4` (794px) or `letter` (816px) |
| `--dark` | auto | Force dark theme |
| `--light` | auto | Force light theme |

### Examples

```bash
# Basic usage
node render.js readme.md

# Specify output path and paper size
node render.js slides.md output.png --paper=letter

# Force dark theme (for dark background images)
node render.js notes.md card.png --dark
```

## Environment Setup

### Windows (current machine)

Already configured. Uses local Edge/Chrome via `puppeteer-core`.

### Linux (headless server)

On Linux servers without a GUI browser, install Chromium:

```bash
# Option 1: Install puppeteer (auto-downloads Chromium)
cd skills/md2img/scripts
npm install puppeteer
npx puppeteer browsers install chrome

# Option 2: Install system Chromium
# Ubuntu/Debian:
sudo apt install -y chromium
# Alpine:
apk add chromium

# Option 3: Set CHROME_PATH env variable
export CHROME_PATH=/usr/bin/chromium
```

**Linux headless prerequisites:**

```bash
# Ubuntu/Debian — required shared libraries
sudo apt install -y libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
  libxkbcommon0 libxcomposite1 libxdamage1 libxrandr2 libgbm1 libasound2 \
  libpango-1.0-0 libcairo2 libxshmfence1

# Alpine
apk add nss atk cups-libs libdrm libxkbcommon libxcomposite libxdamage \
  libxrandr mesa-gbm alsa-lib pango cairo
```

**Emoji font support (Linux):**

Linux默认不支持emoji渲染，需安装emoji字体：

```bash
# Ubuntu/Debian:
sudo apt install -y fonts-noto-color-emoji

# Fedora:
sudo dnf install -y google-noto-emoji-color-fonts

# Arch/Manjaro:
sudo pacman -S noto-fonts-emoji

# Verify:
fc-list | grep -i emoji
fc-match "😀"  # Should return: NotoColorEmoji.ttf
```


### Docker deployment

```dockerfile
FROM node:20-slim

# Install Chromium dependencies and fonts (including emoji support)
RUN apt-get update && apt-get install -y \
    chromium \
    fonts-noto-cjk \
    fonts-noto-color-emoji \
    --no-install-recommends && \
    rm -rf /var/lib/apt/lists/*

# Set CHROME_PATH so puppeteer-core finds it
ENV CHROME_PATH=/usr/bin/chromium
ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true

WORKDIR /app
COPY scripts/package.json scripts/render.js ./
RUN npm install --production

CMD ["node", "render.js"]
```

## Technical Details

- **Markdown parsing**: `marked` v12 with custom renderer for mermaid code blocks
- **LaTeX rendering**: `KaTeX` server-side pre-render (no browser-side JS needed)
- **Mermaid rendering**: `mermaid.js` browser-side rendering via CDN (mermaid requires DOM API, cannot render in Node.js)
- **Browser automation**: `puppeteer-core` (Windows, uses local Edge/Chrome) or `puppeteer` (Linux, bundled Chromium), with auto-detection
- **Output**: 2x DPI PNG (A4: 1588px wide, Letter: 1632px wide)
- **Font stack**: System fonts + CJK fallback (PingFang SC, Microsoft YaHei, Noto Sans SC)

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "No Chrome/Edge/Chromium found" | Install Chrome/Chromium or run `npm install puppeteer` |
| Chinese characters missing on Linux | Install CJK fonts: `apt install fonts-noto-cjk` |
| Emoji显示为方框□ on Linux | Install emoji fonts: `apt install fonts-noto-color-emoji` |
| `/dev/shm` errors on Linux | Use `--disable-dev-shm-usage` (already included) |
| Puppeteer download timeout in China | Set mirror: `PUPPETEER_DOWNLOAD_BASE_URL=https://cdn.npmmirror.com/binaries/chrome-for-testing npx puppeteer browsers install chrome` |
| Screenshot blank/white | Ensure `waitUntil: 'networkidle0'` completes; check font availability |