notion-bg-gen

Mesh-gradient cover images for Notion pages, from a terminal UI or a one-line command.

Try it without installing anything

If you have uv:

uvx notion-bg-gen

That opens the terminal UI. Type a title, press s, and the cover lands in covers/.

Install it properly

Then run:

notion-bg

New to the terminal? The installation guide walks through it one step at a time, including what to do when macOS says the download "cannot be opened".

The terminal UI

Running notion-bg with no arguments opens an interactive app. Everything updates live, and the preview is the real renderer at a smaller size, so what you see is what gets written.

The command line

Every option in the UI is a flag, so covers can be generated in a script, a Makefile, or a CI job.

# One cover, default look
notion-bg generate "Engineering Wiki"

# Pick a palette and a style
notion-bg generate "Roadmap" --palette ocean --style aurora

# A batch, reproducibly
notion-bg generate --from-file titles.txt --seed 7 --out ./covers

# Five variations to choose from
notion-bg generate "Design System" --count 5

Commands

Options

Styles

Palettes

classic, sunset, ocean, candy, forest, ember, lavender, mono - each usable on either theme. Add your own with notion-bg config edit.

Themes

The headline colour is chosen for legibility. If a palette puts a dark field behind dark text, the ink flips automatically so the title stays readable. Override it with --text-color when you want the last word.

Sizes

Any WIDTHxHEIGHT works too, up to 10000px a side.

Using it from a script or an agent

generate is built to be driven by something other than a human:

• --json puts a structured result on stdout and all progress on stderr
• --seed makes output byte-for-byte reproducible
• --dry-run reports the paths it would write
• palettes --json and styles --json make the options discoverable
• Exit codes are 0 success, 1 render failure, 2 bad input
• A bare notion-bg in a pipe or a CI job prints help and exits 2 rather than trying to open a full-screen UI

notion-bg generate "Release Notes" --seed 42 --json

{
  "covers": [
    {
      "path": "covers/release-notes.jpg",
      "text": "Release Notes",
      "seed": 42,
      "palette": "classic",
      "theme": "dark",
      "style": "mesh",
      "width": 3000,
      "height": 1200,
      "format": "jpg",
      "written": true,
      "bytes": 1137482
    }
  ],
  "count": 1
}

More in the automation guide.

Your own palettes

notion-bg config edit

[palettes.brand]
name = "Brand"
description = "Our colours."
colors = ["#0F172A", "#1E40AF", "#3B82F6", "#93C5FD"]

[themes.midnight]
background = "#020617"
text = "#E2E8F0"

notion-bg generate "Internal Docs" --palette brand --theme midnight

Documentation

• Installation - every platform, written for non-developers
• Quickstart
• CLI reference
• Configuration
• Automation and agents
• Contributing
• Changelog

Contributing

Issues and pull requests are welcome. CONTRIBUTING.md covers the setup, which is uv sync and pytest.

License

MIT.

The bundled Inter typeface is used under the SIL Open Font License 1.1.