mdshot

Render beautiful screenshots from Markdown. Powered by Takumi and MD4x.

Features

• Render Markdown to PNG images
• GitHub-flavored styling with headings, lists, tables, code blocks, blockquotes, and more
• Section selection via regex pattern matching
• Watch mode for live re-rendering
• Customizable themes, dimensions, and fonts
• Bundled with Geist font family
• System emoji font support (Linux, macOS, Windows)

Usage

CLI

Usage:
  mdshot <input> [output.png] [options]

Input:
  file.md          Local markdown file
  npm:<package>    README from npm registry
  gh:<owner/repo>  README from GitHub repo

Options:
  -w, --watch              Watch for file changes
  -s, --select <pattern>   Markdown title selector
      --width <px>          Image width
      --height <px>         Image height
  -t, --title <text>        Title text
  -d, --description <text>  Description text
  -h, --help               Show this help

undefinedExamples:undefined

# Render a local markdown file
npx mdshot input.md

# Render with custom output path
npx mdshot input.md output.png

# From an npm package
npx mdshot npm:vue

# From a GitHub repo
npx mdshot gh:unjs/mdshot

# Render a specific section
npx mdshot README.md --select "Installation"

# Watch mode with custom dimensions
npx mdshot notes.md -w --width 800 --height 400

Programmatic

import { mdshot } from "mdshot";

const png = await mdshot("# Hello World\n\nThis is **mdshot**.");

// With options
const png = await mdshot(markdown, {
  width: 800,
  height: 400,
  select: "Usage",
  theme: {
    bg: "#1e1e2e",
    text: "#cdd6f4",
  },
});

undefinedOptions:undefined

Option	Type	Default	Description
width	number	1280	Image width in pixels
height	number	640	Image height in pixels
format	OutputFormat	"png"	Output format
devicePixelRatio	number	2	Device pixel ratio (retina)
theme	Partial<Theme>	-	Custom theme overrides
fonts	Font[]	-	Additional fonts to load
select	string	-	Regex pattern to select sections by heading
title	string	-	Override or add the first heading title
description	string	-	Description line shown below the title

Development

local development

• Clone this repository
• Install latest LTS version of Node.js
• Enable Corepack using corepack enable
• Install dependencies using pnpm install
• Run interactive tests using pnpm dev

License

Published under the MIT license.