Frontmatter

By default Colophon reads a meta_img_props object from a post’s frontmatter, takes the template name from a template field within it, and reads the post slug from a top-level slug.

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

Fields other than the template name are passed through to the template, so what a props block may contain depends on which template reads it. See Templates.

Matching an existing convention

Every part of that is configurable under content:

Option	Default	What it names
propsKey	meta_img_props	The frontmatter key holding the props object.
templateField	template	The field within it naming the template.
defaultTemplate	none	Template to use when that field is absent.
slugField	slug	Top-level field to read the slug from.
slugStrategy	basename	How to derive a slug when there is none.
extensions	.md and .markdown	Which files in the tree are content.
props	none	Build props from a post’s existing frontmatter.

slugStrategy is covered in Output sizes and filenames.

content lives in the config module rather than being a CLI flag because props is a function. generate’s walk option is the programmatic equivalent and takes precedence where both are given.

Using the frontmatter you already have

A site with 200 existing posts gets no images until someone adds a props block to 200 files. Most posts already carry the fields an image needs, just under different names, so map them instead:

export default defineConfig({
  content: {
    defaultTemplate: "banner",
    props: (frontmatter) =>
      frontmatter.draft === true
        ? undefined
        : { title: frontmatter.title, subtitle: frontmatter.description },
  },
});

Point it at your content directory and the site gets its images without a single post being edited.

Returning undefined skips a post

That is the filter for drafts, section indexes and anything else in the tree that is not a page worth sharing. Without it, mapping frontmatter means an image for every markdown file there is.

An explicit props block still wins, field by field

A post that wants a different subtitle writes just that:

---
title: Colophon 2.3.0
description: Autogenerated release notes
meta_img_props:
  subtitle: Per-size config, frontmatter mapping
---

The title still comes from the mapper, and only the subtitle is overridden.

A post declaring a block is never skipped, even where the mapper would have skipped it. Asking for an image outright is the stronger signal.

Slugs from frontmatter

A slug in frontmatter wins over whatever the slug strategy would have derived from the path, which is usually what you want for an SEO-friendly filename.

It has to stay inside the content tree. A derived slug cannot be absolute or contain . or .. segments by construction, as it comes from a relative path. A hand-written frontmatter slug is validated and rejected if it is absolute or contains . or .. segments. Slugs are resolved from the content root, so it takes fewer .. segments to leave the tree than you might expect.