OG Image Branding & Icons
get_branded_og_url is a higher-level helper that renders an OG image with a logo, site name, and/or a built-in Material icon overlaid at the position defined by the active layout preset.
Basic usage
from django_cfg.modules.django_ogimage import get_branded_og_url, DARK_BLUE
params = DARK_BLUE.to_params(title="My Page", description="Subtitle")
# Site name only
url = get_branded_og_url(params, site_name="Acme Corp")
# → /media/ogimage/ab/cd/abcdef....pngParameters
def get_branded_og_url(
params: OGImageParams,
*,
logo_url: str = "", # path or URL to PNG/SVG logo file
icon: str = "", # built-in icon name (e.g. "dashboard")
site_name: str = "", # text label next to logo
layout: OGLayoutPreset = DEFAULT,
request=None, # Django request — returns absolute URL if provided
) -> str: ...Priority: logo_url takes precedence over icon. If both are empty, only the site_name text is rendered.
With a built-in icon
50 top Material Design icons are bundled as SVG files and automatically rasterized at render time:
from django_cfg.modules.django_ogimage import get_branded_og_url, DARK_BLUE, list_icons
# See all available icon names
icons = list_icons()
# ["account_circle", "add", "arrow_back", "dashboard", "email", "home", "settings", ...]
url = get_branded_og_url(
DARK_BLUE.to_params(title="Dashboard"),
icon="dashboard",
site_name="Acme",
)Passing an unknown icon name raises ValueError:
get_branded_og_url(params, icon="nonexistent")
# ValueError: Icon 'nonexistent' not found. Available: account_circle, add, ...With an external logo
Pass a file path to any PNG or SVG file. SVG files are automatically rasterized via skia.SVGDOM:
url = get_branded_og_url(
params,
logo_url="/srv/media/logo.svg",
site_name="Acme Corp",
)With a layout
from django_cfg.modules.django_ogimage import HERO, ARTICLE
# Brand in top-left (HERO layout)
url = get_branded_og_url(params, icon="dashboard", site_name="Acme", layout=HERO)
# Brand in top-left, no accent bar (ARTICLE layout)
url = get_branded_og_url(params, site_name="Acme Docs", layout=ARTICLE)See Layouts for all available layout presets.
Absolute URL
url = get_branded_og_url(params, site_name="Acme", request=request)
# → https://example.com/media/ogimage/ab/cd/abcdef....pngCaching
get_branded_og_url has its own combined cache key:
SHA256[:40](compute_cache_key(params) + json(logo_url, site_name, layout.name))The second call with identical inputs skips rendering entirely and returns the cached file URL immediately.
Built-in icon registry
from django_cfg.modules.django_ogimage import list_icons, get_icon_path
# All available icon names (sorted)
icons = list_icons()
# Path to a specific SVG file
path = get_icon_path("home") # → Path(.../core/assets/icons/home.svg)
path = get_icon_path("missing") # → ValueErrorAvailable icons
10 icons curated for SaaS product OG images:
| Icon | Use case |
|---|---|
dashboard | Overview / home page |
analytics | Metrics, reports, insights |
people | Team, users, collaboration |
payments | Billing, subscriptions, pricing |
security | Access control, compliance |
rocket_launch | Onboarding, launch, getting started |
support_agent | Support, help center |
cloud | Infrastructure, hosting, cloud services |
verified | Trust, verification, quality |
auto_awesome | AI features, automation, highlights |
To refresh the set, run update_icons.py — it downloads the curated set from Google Fonts and bakes them into the package:
python src/django_cfg/modules/django_ogimage/scripts/update_icons.py
Django-CFG