Reference → SEO — Reference

SEO — Reference

The SEO surface is the platform's site-wide SEO control plane. It owns the global SEO defaults that apply when a content record has not set its own values, the per-content-type defaults (e.g., default meta title pattern for products vs blog posts), the robots directives that gate crawler access, the sitemap configuration that decides which records the platform publishes for indexing, and the schema.org defaults that ship with every page.

This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or auditing the site's SEO posture. Customer-facing how-tos live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.

Overview

SEO settings live under the SEO module in SG-Admin, alongside Redirects in the SEO sub-tree. The module renders four primary views — the global defaults page, the per-content-type defaults page, the robots + sitemap page, and the schema defaults page — and exposes a small set of write operations for editing each of those configuration groups.

Unlike most SG-Admin modules, the SEO surface holds no list-of-records; it holds a small set of configuration documents, each rendered as a form. Edits to any document take effect immediately on the public site — there is no separate publish step. This makes the surface high-use; the guards documented under Actions below are designed accordingly.

The SEO defaults participate in a layered defaulting chain. For any single piece of content (a page, a product, a post), the rendered SEO meta is computed as follows: per-record override (if set) → per-content-type default (if set) → global default. The first layer that has a value wins.

Where it lives in SG-Admin:

Sidebar: SG-Admin → SEO → Settings
URL prefix: /sg-admin/seo/
View templates: application/views/Admin/SEO/

The module surface is small (four configuration documents) but the consequences are large — a single change to the global robots directives can take an entire site out of the search index. Adjacent surfaces (Redirects, Pages, Products, Posts) consume the SEO defaults but do not own them.

┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → SEO → Settings │├──────────────────────────────────────────────────────────────────────┤│ ││ ┌────────────────────────┐ ┌────────────────────────────────────┐ ││ │ Global defaults │ │ Per-content-type defaults │ ││ │ ───────────────────── │ │ ───────────────────────────────── │ ││ │ Site title │ │ Pages — {title} | {site} │ ││ │ Site description │ │ Products — {name} | {site_brand} │ ││ │ Default OG image │ │ Posts — {title} | Blog │ ││ │ Default canonical │ │ Custom — [+ Add content type] │ ││ └────────────────────────┘ └────────────────────────────────────┘ ││ ││ ┌────────────────────────┐ ┌────────────────────────────────────┐ ││ │ Robots + sitemap │ │ Schema defaults │ ││ │ ───────────────────── │ │ ───────────────────────────────── │ ││ │ Index discouraged: OFF │ │ Organization schema ON │ ││ │ robots.txt │ │ Breadcrumb schema ON │ ││ │ Sitemap path │ │ Article schema (posts) ON │ ││ │ Sitemap content types │ │ Product schema ON │ ││ └────────────────────────┘ └────────────────────────────────────┘ │└──────────────────────────────────────────────────────────────────────┘

Actions

The SEO surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.

Edit global defaults

Loads the global defaults form, pre-populated. The form covers:

Site title — used as the default meta title and as the brand suffix in per-content-type patterns.
Site description — used as the default meta description for records that have not set their own.
Default OG image — used for OpenGraph and Twitter card image when a record has no per-record image.
Default canonical scheme — controls whether canonical URLs use the apex domain or a configured preferred host.
Default lang — used for the document lang attribute and as a hint for hreflang where applicable.

Submit replaces the stored defaults. Edits propagate to any rendered page on the next request.

Edit per-content-type defaults

Loads the per-content-type form. The form is a small grid — one row per registered content type (pages, products, posts, plus any custom content types). Each row carries a meta-title pattern, a meta-description pattern, an optional content-type-specific OG image, and a sitemap-inclusion toggle.

Patterns support a small set of variables. Common variables include the record's title, the site's title or brand, the record's category, and the record's author. Unrecognized variables in a pattern fall back to empty.

Engineering note: patterns are evaluated server-side at page-render time. Empty variable values do not leave behind " | | site" artifacts — the platform's pattern evaluator collapses adjacent separators and trims.

Edit robots directives

Loads the robots + sitemap form. The form covers:

Index discouraged — a site-wide toggle that, when on, emits a noindex meta tag on every page and includes a corresponding directive in robots.txt. The toggle is intentionally prominent and includes a confirmation step.
robots.txt — the served robots.txt content. The platform ships a sane default; operators with specific crawler needs can override. The form includes a validator that flags common mistakes (block of /sitemap.xml, disallow of the site root).
Sitemap path — the URL at which the platform serves the sitemap. Defaults to /sitemap.xml.
Sitemap content types — checkboxes per content type. Only checked types appear in the served sitemap.
Sitemap last-modified strategy — controls whether the sitemap reports the record's updated_at or a coarser daily timestamp (useful for sites with high-frequency content edits that do not warrant re-crawl).

Engineering note: the index-discouraged toggle is the single highest-consequence control on this surface. The toggle's save handler emits an extra confirmation that names the consequence ("the site will be removed from search index over the following days"); the toggle cannot be flipped via bulk import.

Edit schema defaults

Loads the schema defaults form. The form is a list of schema.org types the platform supports out of the box (Organization, Breadcrumb, Article, Product, FAQ, HowTo, WebSite, plus custom types) with per-type toggles and per-type configuration where applicable.

Organization — site-wide schema. Fields cover legal name, logo, social URLs, contact info.
Breadcrumb — auto-emitted on pages with breadcrumb context. No per-record config.
Article — emitted on blog posts. Fields cover default author fallback, publisher reference.
Product — emitted on product pages. Pulls from the product record; field-mapping is editable.
FAQ / HowTo / custom — emitted where the record carries the appropriate marker.

Submit replaces the stored schema configuration. Schema is emitted as JSON-LD in the page head.

Preview SEO output for a URL

Sub-action available on the global defaults page. Operators paste a candidate URL and the platform shows the SEO output (computed meta title, meta description, canonical, OG block, schema JSON-LD) that would render for that URL given the current configuration. Read-only — does not write.

Reset to platform defaults

Each of the four configuration documents includes a reset-to-default action. Reset replaces the current configuration with the platform-shipped defaults. The action is gated behind a confirmation prompt and emits an Activity Log entry with the prior configuration attached.

Data model

The SEO configuration carries the following documents. Each is a single record per site (not a list).

Document	Conceptual shape	Notes
`global_defaults`	object	site_title, site_description, default_og_image, default_canonical_scheme, default_lang
`per_type_defaults`	array	One row per content type — meta_title_pattern, meta_description_pattern, og_image_override, sitemap_included
`robots`	object	index_discouraged, robots_txt_content, sitemap_path, sitemap_content_types, sitemap_lastmod_strategy
`schema_defaults`	object	Per-type toggles + per-type configuration

Layered defaulting chain. For any single rendered page, the SEO meta is computed by walking three layers in order — per-record overrides → per-content-type defaults → global defaults. The first layer that has a value wins. Empty string is treated as a value (i.e., a deliberate clear); only null / missing falls through.

Sitemap inclusion semantics. A content record appears in the served sitemap if and only if its content type is checked in the robots-and-sitemap configuration AND the record itself is in a sitemap-eligible state (published, not soft-deleted, no per-record noindex override).

Schema reference tracking. Schema configurations may reference Media library records (logo, publisher logo) and User records (default author). Deleting a referenced record orphans the reference but does not break schema emission — the platform falls back to empty for the orphaned field.

PAGE RENDER REQUEST│▼┌──────────────────────────────────────┐│ Layer 1: Per-record override ││ (the page / product / post itself) │└─────────────┬────────────────────────┘│ if field empty, fall through▼┌──────────────────────────────────────┐│ Layer 2: Per-content-type default ││ (pattern evaluation: {title} | etc.) │└─────────────┬────────────────────────┘│ if field still empty, fall through▼┌──────────────────────────────────────┐│ Layer 3: Global default ││ (site_title, site_description,...) │└─────────────┬────────────────────────┘│▼Final rendered SEO metaEmitted in <head> + JSON-LD

Permissions

Access to the SEO surface is gated at two layers.

Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the SEO surface.

Layer 2 — per-action capability. Within SG-Admin, each SEO action checks a capability associated with the calling operator's role. The default role configuration uses the platform's base roles augmented with an SEO Operator role. The capability map is:

Capability	Administrator	SEO Operator	Editor	Viewer
View SEO settings	✔	✔	✔	✔
Edit global defaults	✔	✔	—	—
Edit per-content-type defaults	✔	✔	—	—
Edit robots directives	✔	✔	—	—
Toggle `index_discouraged`	✔	—	—	—
Edit `robots.txt` content	✔	✔	—	—
Edit schema defaults	✔	✔	—	—
Preview SEO output	✔	✔	✔	✔
Reset to platform defaults	✔	—	—	—

Custom roles defined under Settings → Roles override the default map. The capability slugs are stable; the role slugs are configurable.

The index_discouraged toggle and the reset action are intentionally restricted to Administrators — both are high-consequence operations that should not be routine.

Self-protection rules. Editing robots.txt validates the content against a small set of "you almost certainly did not mean this" rules — disallowing the site root, blocking the served sitemap path, blocking common search engine crawlers explicitly. The validator emits warnings (not rejections); the operator may proceed if the intent is genuine.

The index_discouraged toggle requires an extra confirmation step on its save handler. The confirmation names the consequence in operator language ("the site will be removed from search index over the following days") and requires re-entry of the toggle's intended new value before persisting.

Audit. Every write — global defaults, per-content-type defaults, robots directives, schema defaults, reset-to-default — emits an Activity Log entry with the full before / after configuration attached. The log records the acting operator, the document changed, and the field-level diff. Activity Log retention is governed by the site's general settings.

REQUEST│▼┌───────────────────────────┐│ Admin gate │ unauth → reject└─────────────┬─────────────┘│ authed▼┌───────────────────────────┐│ Capability check │ role lacks cap → reject│ (per-document, per-role) │└─────────────┬─────────────┘│ allowed▼┌───────────────────────────┐│ High-consequence guard │ index_discouraged toggle,│ (subset of writes) │ reset-to-default → extra│ │ confirmation step└─────────────┬─────────────┘│ passes▼action executes│▼Activity Log entry(with before / after diff)

Related references

Pages — Reference. Per-page SEO overrides are managed on the page record. Empty per-page fields fall through to the per-content-type and global defaults documented here.
Products — Reference. Per-product SEO overrides are managed on the product record. Same defaulting chain applies.
Posts — Reference. Per-post SEO overrides are managed on the post record. Same defaulting chain applies.
Redirects — Reference. Redirects and canonical URLs interact. The Redirects reference documents the resolution order when the two would disagree.
Settings — Reference. Owns the registered content types — adding a content type adds a row to the per-content-type SEO defaults grid.
Media — Reference. Default OG images and schema logos reference the Media library. Deleting a referenced media record orphans the reference but does not break SEO emission.
Activity Log — Reference. SEO configuration changes are the most consequential entries in the Activity Log. Operators auditing search-index changes should filter by the SEO surface.

For the corresponding customer-facing walkthrough — setting site-wide SEO defaults, configuring per-content-type meta patterns, debugging a search-index drop — see the SEO section of the customer docs at /docs/seo.

On this page

Guides

Reference

Changelog

Roadmap