159 lines
4.8 KiB
Markdown
159 lines
4.8 KiB
Markdown
---
|
||
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 |
|