Reference: Settings (SEO_SUITE)¶

All configuration lives in a single SEO_SUITE dict in settings.py. Keys you omit inherit the package defaults shown below.

# settings.py

SEO_SUITE = {
    # ... only the keys you want to change ...
}

The DEFAULTS and SITE_DEFAULTS dicts are deep-merged with the built-in values rather than replaced wholesale — you only need to specify keys you want to override within them.

Full reference¶

Resolution¶

Key	Type	Default	Description
`RESOLVER_CLASS`	dotted import string	`"seo_suite.resolver.Resolver"`	The resolver class. Swap to customise collection or merging. Must be a subclass of `seo_suite.resolver.BaseResolver`.
`SITE_ID_RESOLVER`	dotted import string or `None`	`None`	A callable `(request) -> int \\| None` that returns the current site ID. When `None`, the standard fallback chain is used (sites framework → `settings.SITE_ID`).

Global metadata defaults (lowest precedence)¶

Key	Type	Default	Description
`DEFAULTS`	dict	See below	Partial metadata applied to every page as the lowest-priority layer. Deep-merged with the built-in defaults.
`DEFAULTS.title_suffix`	str	`""`	Appended to every page title (e.g. `" \\| My Site"`).
`DEFAULTS.robots`	str	`"index,follow"`	Default robots directive.
`DEFAULTS.og`	dict	`{"type": "website"}`	Default Open Graph tags.
`DEFAULTS.twitter`	dict	`{}`	Default Twitter card tags.

Per-site defaults¶

Key	Type	Default	Description
`SITE_DEFAULTS`	dict	`{}`	Maps site ID (int) or `None` to a partial-metadata dict. Applied at priority 20, above global defaults. `None` key acts as a catch-all for unmatched sites.

Example:

SEO_SUITE = {
    "SITE_DEFAULTS": {
        1: {"title_suffix": " | Main Site", "og": {"site_name": "Main Site"}},
        2: {"title_suffix": " | Blog", "og": {"site_name": "Blog"}},
    },
}

Canonical URL¶

Key	Type	Default	Description
`CANONICAL_DOMAIN`	str or `None`	`None`	Force all canonicals to this domain (e.g. `"www.example.com"`). When `None`, the request `Host` header is used.
`FORCE_HTTPS_CANONICAL`	bool	`True`	Upgrade any `http://` canonical to `https://`.
`LIST_CANONICAL_INCLUDES_PAGE`	bool	`True`	When `True`, `SeoListViewMixin` appends `?page=N` to the canonical for pages > 1. When `False`, all pages share the same canonical.

hreflang¶

Key	Type	Default	Description
`HREFLANG_X_DEFAULT`	bool	`True`	Whether `build_hreflang_alternates` adds an `x-default` entry pointing to the `LANGUAGE_CODE` URL.

Caching¶

Key	Type	Default	Description
`CACHE_TTL`	int	`0`	Cache TTL in seconds for resolved metadata. `0` disables caching. Only object-backed resolutions (model instances with a PK) are cached.
`CACHE_BACKEND`	str	`"default"`	Django cache alias to use.
`CACHE_KEY_PREFIX`	str	`"seosuite:v1"`	Prefix for all cache keys. Change this to invalidate all cached entries at once.

Optional providers¶

Key	Type	Default	Description
`OBJECT_MODELS`	list of str	`[]`	Allowlist for the `seoobject` contrib app. Format: `["app_label.model_name"]` (case-insensitive). Only models in this list trigger a `SeoObject` lookup.

JSON-LD¶

Key	Type	Default	Description
`DEFAULT_SCHEMA_PROFILES`	list of str	`[]`	Schema profile keys applied to every page at the global defaults layer (priority 10).
`JSONLD_SERIALIZER`	dotted import string	`"seo_suite.schema.default_serializer"`	A callable `(dict) -> str` that serialises a JSON-LD dict to a string. The default escapes `<`, `>`, and `&` to prevent injection.

robots.txt¶

These settings control the versioned robots.txt workflow. They have no effect on the SEO metadata resolver and do not change the <meta name="robots"> tag.

Key	Type	Default	Description
`ROBOTS_TXT_FALLBACK`	str	`"User-agent: *\nAllow: /"`	The body served at `/robots.txt` when no database version is active for the current site.
`ROBOTS_SITEMAP_URLS`	list of str	`[]`	URLs appended to every served `robots.txt` as `Sitemap:` lines. Relative URLs are made absolute using the incoming request.
`ROBOTS_CACHE_TTL`	int	`0`	Cache TTL in seconds for the rendered `robots.txt` body. `0` disables caching. The cache is invalidated automatically whenever any version is saved or activated. Uses the same backend as `CACHE_BACKEND`.

Complete example¶

SEO_SUITE = {
    # ---- resolution ----
    "RESOLVER_CLASS": "seo_suite.resolver.Resolver",
    "SITE_ID_RESOLVER": None,

    # ---- global metadata defaults ----
    "DEFAULTS": {
        "title_suffix": " | My Site",
        "robots": "index,follow",
        "og": {
            "type": "website",
            "site_name": "My Site",
        },
        "twitter": {},
    },

    # ---- per-site defaults ----
    "SITE_DEFAULTS": {},

    # ---- canonical ----
    "CANONICAL_DOMAIN": "www.mysite.com",
    "FORCE_HTTPS_CANONICAL": True,
    "LIST_CANONICAL_INCLUDES_PAGE": True,

    # ---- hreflang ----
    "HREFLANG_X_DEFAULT": True,

    # ---- caching ----
    "CACHE_TTL": 300,
    "CACHE_BACKEND": "default",
    "CACHE_KEY_PREFIX": "seosuite:v1",

    # ---- optional providers ----
    "OBJECT_MODELS": [],

    # ---- JSON-LD ----
    "DEFAULT_SCHEMA_PROFILES": [],
    "JSONLD_SERIALIZER": "seo_suite.schema.default_serializer",

    # ---- robots.txt ----
    "ROBOTS_TXT_FALLBACK": "User-agent: *\nAllow: /",
    "ROBOTS_SITEMAP_URLS": [],
    "ROBOTS_CACHE_TTL": 0,
}