social-card

Generate beautiful social card images with a fluent builder API. OG, Twitter, and GitHub presets with dark, light, and midnight themes. Single dependency: Pillow.

pip install social-card

PyPI ClawHub Source

Quickstart

from social_card import SocialCard

SocialCard("og") \
    .title("My Project") \
    .subtitle("A cool tool for builders") \
    .badge("huje.tools") \
    .footer("pip install my-project") \
    .accent("#f97316") \
    .glow() \
    .render("card.png")
      

Presets

Choose a preset to set the canvas size for your target platform.

Preset	Size	Use Case
`og`	1200x630	Open Graph (Facebook, LinkedIn, general)
`twitter`	800x418	Twitter/X cards
`github`	1280x640	GitHub repository social preview
`square`	1080x1080	Instagram, general square format

Themes

Built-in color themes for quick styling.

Theme	Background	Text	Accent
`dark`	`#0f172a`	`#f8fafc`	`#3b82f6`
`light`	`#ffffff`	`#0f172a`	`#3b82f6`
`midnight`	`#030712`	`#f9fafb`	`#8b5cf6`

Builder API

All methods return self for fluent chaining.

Method	Description
`.badge(text)`	Small label at top
`.title(text)`	Main heading
`.subtitle(text)`	Description below title
`.footer(text)`	Bottom text
`.accent(color)`	Override accent color
`.cards(labels)`	Mini card pills
`.skill_cards(skills)`	Structured skill cards with name, label, code
`.grid()`	Background grid pattern
`.glow()`	Accent color glow effect
`.render(path) → Image`	Save to file
`.render_bytes(fmt="PNG") → bytes`	Return as bytes

Skill Cards Example

SocialCard("og").skill_cards([
    {"name": "Nostr|Key", "label": "Identity", "code": "pip install nostrkey"},
    {"name": "sense-memory", "label": "Persistence", "code": "pip install sense-memory"},
]).render("skills.png")
      

Security

Path traversal blocked in render paths
File extensions restricted: .png, .jpg, .jpeg, .webp
Image dimensions capped at 4096x4096
Text length limits on all fields
No network access — purely local rendering
No telemetry

Dependency

Pillow — that's it.

Part of the huje.tools Ecosystem

social-card is part of huje.tools. It's used across the Humanjava ecosystem to generate OG images for landing pages, PyPI packages, and social shares. The OG images on this very site were generated with social-card.