139 lines
4.4 KiB
Markdown
139 lines
4.4 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 — Markdown → PNG
|
|
|
|
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**: auto-detects system preference, or override with `--dark`/`--light`
|
|
- **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 ~/.workbuddy/skills/md2img/scripts
|
|
npm install puppeteer
|
|
npx puppeteer browsers install chrome
|
|
|
|
# Option 2: Install system Chromium
|
|
# Ubuntu/Debian:
|
|
sudo apt install -y chromium-browser
|
|
# CentOS/RHEL:
|
|
sudo yum install -y chromium
|
|
# Alpine:
|
|
apk add chromium
|
|
|
|
# Option 3: Set CHROME_PATH env variable
|
|
export CHROME_PATH=/usr/bin/chromium-browser
|
|
```
|
|
|
|
**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
|
|
```
|
|
|
|
### Docker deployment
|
|
|
|
```dockerfile
|
|
FROM node:20-slim
|
|
|
|
# Install Chromium dependencies
|
|
RUN apt-get update && apt-get install -y \
|
|
chromium \
|
|
fonts-noto-cjk \
|
|
--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
|
|
|
|
ENTRYPOINT ["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` |
|
|
| `/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 |
|