dihechen/pageshot repository overview

⁠pageshot

English | 简体中文⁠

pageshot is a self-contained HTTP / Unix Socket service: send it a markdown document (or pre-styled HTML) and get back a high-DPI PNG, JPEG or WebP — complete with LaTeX math, syntax highlighting and responsive layout.

⁠Features

• Adaptive sizing — any markdown length renders as one image; viewport grows naturally
• Markdown or raw HTML — pass markdown for the themed pipeline, or html to render your own pre-styled markup
• Five beautiful themes — GitHub Light/Dark, Notion, Academic, Dracula
• Crystal-clear text — deviceScaleFactor: 2 (retina) by default
• Full LaTeX support — inline $...$ and block $$...$$ formulas via KaTeX
• Extensive code highlighting — 40+ languages via Shiki (VS Code engine)
• Dual protocol — HTTP + Unix socket in the same process
• Production-ready — warmup at startup, concurrency limits, graceful shutdown

⁠Security notice

• Run this service only in a trusted environment (for example, internal network / trusted callers).
• Rendering input is not fully sanitized (especially raw html), and renderer content may request external resources.
• Do not expose this service directly to untrusted public input without an additional isolation/sanitization layer.

⁠Quick start

# Install dependencies and browser
pnpm install
pnpm playwright:install

# Start the server (watches for changes in dev mode)
pnpm dev

In another terminal:

# HTTP — synchronous markdown render
curl -X POST http://localhost:12000/images \
  -H 'Content-Type: application/json' \
  -d '{"markdown": "# Hello\n\n$$E=mc^2$$", "theme": "github-light"}' \
  -o hello.png

# HTTP — render raw HTML (no theme/KaTeX CSS — caller controls all styling)
curl -X POST http://localhost:12000/images \
  -H 'Content-Type: application/json' \
  -d '{"html": "<div style=\"font-family:sans-serif\"><h1>Hi</h1></div>"}' \
  -o html.png

# Unix Socket (fastest for local use)
curl --unix-socket /var/run/pageshot.sock \
  -X POST http://localhost/images \
  -H 'Content-Type: application/json' \
  -d '{"markdown": "# Hello\n\n$\\int_0^1 x \\,dx = \\frac{1}{2}$", "theme": "dracula"}' \
  -o hello.png

⁠Themes

Preview all of them in the themes documentation⁠.

⁠API

Interactive documentation is available at http://localhost:12000/documentation once the server is running.

⁠POST /images

Synchronous render. Content negotiation via the Accept header:

Request body (exactly one of markdown or html is required)

Example (raw image)

curl -X POST http://localhost:12000/images \
  -H 'Content-Type: application/json' \
  -d @examples/sample.json \
  -o out.png

Example (JSON metadata only)

curl -X POST http://localhost:12000/images \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"markdown": "# Hi"}' | jq '.height'

⁠Asynchronous rendering

For large documents or when you don't want to block the connection:

# Create a render job
curl -X POST http://localhost:12000/renders \
  -H 'Content-Type: application/json' \
  -d '{"markdown": "# Hello", "theme": "notion"}'
# → {"id":"...","status":"queued","location":"/renders/..."}

# Poll for completion
curl http://localhost:12000/renders/{id}
# → {"status":"completed","result":{"imageUrl":"/renders/{id}/image",...}}

# Fetch the image
curl http://localhost:12000/renders/{id}/image -o out.png

⁠GET /themes

{ "themes": [
  { "name": "github-light" },
  { "name": "github-dark" },
  { "name": "notion" },
  { "name": "academic" },
  { "name": "dracula" }
]}

⁠GET /health

Returns { "status": "ok", "browser": "ready" } once the render pipeline is warmed up.

See docs/api.md⁠ for full details.

⁠Environment variables

⁠Docker

docker build -t pageshot .
docker run -p 12000:12000 -e PAGESHOT_CONCURRENCY=4 pageshot

See docs/deployment.md⁠ for systemd, health-check and tuning details.

⁠License

MIT