inkframe

Render beautiful visual images from markdown content, accessible via CLI, SDK, and Agent Skill.

Powered by inkframe.dev.

Quickstart

Headless render mode

Call Inkframe API to render. Great for programmatical use.

# inline content
npx inkframe render --content "# Hello Inkframe" --output out.png

# or from file content
npx inkframe render --content @path/to/markdown.md --output out.png

The CLI includes a free shared API key so you can try it instantly — no signup required. The shared key may be rate-limited or rotated over time; bring your own API key for production use. Open an issue to request API key.

Inkframe Playground render mode

Open "Inkframe Playground" in browser for preview, adjust, and manual image export.

# inline content
npx inkframe open --content "# Hello Inkframe"

# or from file content
npx inkframe open --content @path/to/markdown.md

Requirements

• Node.js 18+

Installation

Skill

# Strongly recommend if you use inkframe with agent: Claude Code, Codex, etc.
npx skills add ericjy/inkframe

CLI

# Install CLI globally to skip typing npx - below examples assume this
pnpm add -g inkframe

TyepScript SDK

# You only need this if you are integrating inkframe through SDK
pnpm add inkframe

Using inkframe with agent

First install the skill (see above). Then prompt your agent:

Use inkframe to convert markdown to image

Using inkframe without agent

0. Preview in the browser

Open the Inkframe playground with your content pre-loaded.

# Inline content
inkframe open --content "# Hello World"

# From files
inkframe open --content @post.md --design @design.json

This opens your browser with the playground pre-populated so you can preview and tweak before rendering.

1. Render with a template

The quickest way to get started — pick a template and render your content with it.

# See what templates are available
inkframe templates list

# Render using a template (uses template's own content and design)
inkframe render --template tmpl_PWfUUDlVw --output out.png

# Or bring your own content (file)
inkframe render --content @post.md --template tmpl_PWfUUDlVw --output out.png

# Or bring your own content (inline)
inkframe render --content "# My Post" --template tmpl_PWfUUDlVw --output out.png

2. Customize a design

Extract a template's design as a starting point, tweak it, then render with your custom version.

# Extract the design from a template
inkframe templates get tmpl_PWfUUDlVw --design-only --output design.json

# Edit design.json to your liking, then render with a file
inkframe render --content @post.md --design @design.json --output out.png

# Inline content + inline design
inkframe render --content "# My Post" --design '{"backgroundKey":"ocean","colorPaletteKey":"pure-white"}' --output out.png

3. Automate with the SDK

Use the TypeScript SDK to render images programmatically in your scripts or pipelines.

import { InkframeClient } from "inkframe";

// Uses free shared key by default, or pass your own
const client = new InkframeClient({ apiKey: process.env.INKFRAME_API_KEY });

const result = await client.render({
  content: "# Hello World\n\nThis is a visual post.",
  design: { backgroundKey: "ocean", dimensionSpecKey: "instagram-4:5" },
});

console.log(result.resultUrl);

---

Using the CLI

# Works out of the box with the free shared key
inkframe render --content "# Hello World"

# Or set your own API key
export INKFRAME_API_KEY=your_api_key
inkframe render --content "# Hello World"

# Render from a markdown file (prefix with @)
inkframe render --content @post.md --output out.png

# Use a template (uses template's own content and design)
inkframe render --template tmpl_PWfUUDlVw --output out.png

# Use a template with your own content
inkframe render --content @post.md --template tmpl_PWfUUDlVw --output out.png

# Use a design file
inkframe render --content @post.md --design @design.json --output out.png

# Use inline design JSON
inkframe render --content "# Hello World" --design '{"backgroundKey":"ocean"}' --output out.png

# List available templates
inkframe templates list

# Get full template JSON
inkframe templates get tmpl_PWfUUDlVw

# Get only the design object
inkframe templates get tmpl_PWfUUDlVw --design-only

# Save to file
inkframe templates get tmpl_PWfUUDlVw --output template.json
inkframe templates get tmpl_PWfUUDlVw --design-only --output design.json

# Open playground in browser (free, no API key needed)
inkframe open --content "# Hello World"
inkframe open --content @post.md --design @design.json

Using the TypeScript SDK

import { InkframeClient } from "inkframe";

// Uses free shared key by default, or pass your own
const client = new InkframeClient({ apiKey: process.env.INKFRAME_API_KEY });

try {
  const result = await client.render({
    content: "# Hello World",
    design: {
      backgroundKey: "ocean",
      colorPaletteKey: "pure-white",
      dimensionSpecKey: "instagram-4:5",
    },
  });
  console.log(result.resultUrl); // https://...
} catch (error) {
  console.error("Render failed:", error.message);
}

// List templates without thumbnailUrl
const templates = await client.listTemplates({ exclude: ["thumbnailUrl"] });

Multi-Page Content

Content can contain \pagebreak to separate pages (slides). The API renders one image per request — if your content has \pagebreak separators, only the first page is rendered. The inkframe.dev studio UI supports rendering all pages at once.

To render multi-page content via the CLI or SDK, split the content yourself and render each page in parallel:

# Render each page separately, in parallel
inkframe render --content @page1.md --design @design.json --output slide1.png &
inkframe render --content @page2.md --design @design.json --output slide2.png &
inkframe render --content @page3.md --design @design.json --output slide3.png &
wait

// SDK: render pages in parallel
const pages = fullContent.split("\\pagebreak");
const results = await Promise.all(
  pages.map((page) => client.render({ content: page.trim(), design })),
);

Development

# Install dependencies
pnpm install

# Build (outputs to dist/)
pnpm build

# Watch mode
pnpm dev

# Type check without building
pnpm typecheck

Test the open command locally (point to local webapp):

pnpm build
node dist/cli.js open --content "# Hello World" --base-url http://localhost:3001

Test the CLI locally against the live API:

pnpm build
INKFRAME_API_KEY=your_api_key node dist/cli.js render --content "# Hello World"

Test against a local server:

INKFRAME_API_KEY=your_api_key node dist/cli.js render --content "# Hello World" --base-url http://localhost:3000

Simulate a global install:

pnpm link --global

export INKFRAME_API_KEY=your_api_key
inkframe render --content "# Hello World"

Tier-list image skill

Install just the tier-list skill:

npx skills add https://github.com/ericjy/inkframe/skills --skill tier-list-image

Requirements:

• Node.js 18+
• agent-browser installed and available on PATH
• browser runtime installed for agent-browser

Recommended setup:

npm install -g agent-browser
agent-browser install

Then prompt your agent with a ranking request such as:

Use the tier-list-image skill.

Make a 4:5 editorial tier-list image titled "Best AI Coding Tools".
S: Codex, Claude Code
A: Cursor, Windsurf
B: Copilot

Save the output locally.

The skill will:

1. convert the request into a tier-list spec JSON
2. render HTML from that spec
3. screenshot the HTML to a PNG using agent-browser

It also supports custom tier vocabularies, including Chinese labels like 夯爆了 / 夯 / 顶级 / 人上人 / NPC / 拉完了, and preserves the order exactly as provided.

License

MIT