Colophon

Colophon generates social meta images, the Open Graph and share-card images a platform shows when someone posts a link to your site. You describe an image in a post’s frontmatter and Colophon renders branded PNGs at the sizes you need.

The name comes from the printer’s colophon, the emblem or inscription a publisher places on a finished work.

Install

pnpm add @kensio/colophon

@resvg/resvg-js rasterises the SVG to PNG, and shiki provides the grammars and themes for the code template. No headless browser is involved.

Examples

Every one of these was drawn by Colophon from a few lines of frontmatter, and they are redrawn from scripts/samples.mts each time the site is built. Between them they show every theme, most of the templates and ten of the textures. Click one to see it full size, or open the playground to build your own.

• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 
• 

×

npm@kensio/colophon npm package

GitHubKensioSoftware/colophon GitHub repo

A first image

Add image props to a post’s frontmatter:

---
title: My post
meta_img_props:
  template: banner
  title: "@kensio/colophon"
  subtitle: Generate social meta images from frontmatter
  version: 1.2.0
---

Then run Colophon over the content tree:

colophon content --config colophon.config.ts

For every file that declares meta_img_props, Colophon writes one PNG per output size next to the post, named <slug>-<size>.png.

Getting started covers this in full, including where else the images can be written and how the site reads back what was generated.

What it does

• Reads a post’s frontmatter rather than imposing a fixed schema, so a site can generate images from the fields its posts already carry.
• Renders from templates. A small registry of layouts, picked per post from frontmatter, and you can register your own.
• Highlights code. The code template renders a snippet with real VS Code theme colours.
• Takes its branding from config. Colours, gradient, fonts, footer and badge, so nothing is tied to one site’s stylesheet.
• Renders several sizes from one input. A 1:1 square and a 1.91:1 landscape by default, or whatever set you configure.
• Writes down what it generated. A JSON manifest of every page’s images, and the Open Graph and Twitter tags that go with them.
• Skips work it has already done. Each image carries a hash of what it was rendered from, so a rebuild renders only what changed.

This site’s own share images are generated by Colophon.