SEOmatic for Craft CMS: complete guide

If you build with Craft, you almost certainly run SEOmatic. It has been the most widely used Craft SEO plugin for years, maintained by nystudio107 and the patterns it introduced have stayed stable across major Craft versions. SEOmatic 5 is the current line and supports Craft 5. nystudio107 has historically shipped major-version compatibility for its plugins, so I expect Craft 6 support to follow once that version is generally available. The plugin is not going anywhere.

This is a guide to thinking about SEOmatic structurally rather than clicking through screens. The control panel layout changes between versions but the model behind it does not. Understand the model and the screens become navigation.

What SEOmatic actually does

SEOmatic generates the SEO output a page needs. Meta tags. Open Graph and Twitter cards. JSON-LD structured data. Sitemaps. The robots.txt file. Hreflang for multi-site. Sensible defaults for every page on a site.

The trick is that it does all of this through a layered configuration model. Site-wide defaults sit at the top. Section-level overrides sit below them. Entry-level overrides sit below those. A field type lets editors customise individual entries. Each layer falls back to the one above it. You configure once and the rest cascades.

That cascading model is the part that takes a while to get right. Most SEOmatic mistakes I see are configurations that fight the cascade rather than work with it.

The main configuration areas

SEOmatic groups its configuration into a handful of areas: meta settings for what goes in the head of a page, sitemap settings, frontend templates and tracking. Knowing what each one is for stops you putting configuration in the wrong place.

Meta settings hold everything that ends up in the head of a page. Title, description, canonical, robots directives, social cards, JSON-LD. Under the hood SEOmatic splits these into a set of meta object containers, one each for the title tag, the meta tags, the link tags, script tags and the JSON-LD block. You rarely touch them directly but it helps to know they are there. This is where most of the day-to-day work lives.

Sitemap settings handle the XML sitemap. Which sections appear in the sitemap, at what priority, with what change frequency, with what images. SEOmatic generates the sitemap automatically for any section you enable it for and the sitemap index ties them together.

Frontend templates handle robots.txt, humans.txt, ads.txt and security.txt. Edit them once and SEOmatic serves them on the relevant routes.

Tracking handles analytics scripts and pixel injection. Many teams disable this and use a tag manager instead, which is the cleaner approach for any site that runs more than one tracking script.

Content SEO settings as the global default

The content SEO settings are where you define the defaults for every section. For each section you set the title template, description template, image source, OG type, Twitter card type and whether the section appears in the sitemap.

Title and description templates use Twig. You can pull from any field on the entry. A typical articles section title template might be something like the entry title followed by a separator and the site name. A typical description template might pull from a dedicated SEO description field if it exists, falling back to an excerpt, falling back to a truncated body.

The fallback chain is the part that matters. Editors will not fill in every SEO field on every entry. Your templates should produce a sensible result even when the SEO-specific fields are empty. Site name, page title and a content-derived description should always be present.

The SEO settings field as the entry-level override

SEOmatic ships a field type called SEO Settings. Drop it into the field layout of any section that needs editor-level control and editors get a UI per entry for overriding title, description, image, robots directives and social cards.

The pattern that ages well is to add this field to every section that publishes content but make the editorial UX minimal. Most editors should not be hand-writing meta tags. They should be writing a good page title and a good description and SEOmatic should be deriving the rest. The override is for the cases that need it, not the default workflow.

A common mistake is to hide the field entirely so only developers can edit it. The opposite mistake is to expose every field on every entry and clutter the editor experience. The middle path is to expose the four or five fields editors will actually use and hide the rest behind an advanced toggle.

Schema types and structured data

Structured data is where SEOmatic earns its licence fee on a content-heavy site. SEOmatic generates JSON-LD using schema.org types, automatically inferring the right structure from the section configuration.

For an article section, SEOmatic produces Article schema by default with the right properties: headline, datePublished, author, image. For a product section, you can switch to Product schema and the field mappings change. For a local business, Organization or LocalBusiness schema applies. The plugin handles dozens of schema types and you pick the one that fits.

The thinking that matters is which schema type maps to which section before you configure the rest. Get this right at the start and the structured data flows out of your existing content without extra editorial effort. Get it wrong and you spend the rest of the project patching it.

Test your JSON-LD output with Google's Rich Results Test and the Schema Markup Validator when you launch and at major Craft updates. SEOmatic produces valid JSON-LD by default but custom configurations can introduce mistakes that only show up in Search Console.

Multi-site SEO handling

On a Craft multi-site, SEOmatic configuration is per-site. Each site has its own meta defaults, its own sitemap, its own robots.txt. That is the right model because language variants need their own titles and descriptions.

Hreflang tags are generated automatically based on the multi-site structure. SEOmatic looks at which entries exist in which sites and produces the cross-references. The one configuration to check is the language code and region code per site. Set them once and the rest works.

A pattern that catches people out is forgetting to enable the sitemap per site. If you launch a multi-site and Google is not indexing one of the language variants, the first place to look is whether that site has a sitemap turned on.

Social meta and image generation

Open Graph and Twitter card configuration sits in the same field layout as the rest. Editors pick a social image per entry if they need to, otherwise it falls back to a section default, then to a site default. The cascade prevents the worst-case of an article shared on social with no image.

SEOmatic supports generating social images dynamically from a template if you have a complex requirement. Most sites do not need this. A well-cropped article image with the focal-point system from Craft is usually enough.

The transform configuration for social images is one of the small details that quietly matters. Open Graph recommends 1200 by 630. Twitter recommends 1200 by 600 for the large card. Configure those transforms in SEOmatic so editors do not have to think about it per entry.

Sitemap behaviour and what to exclude

The default behaviour is to include every entry in every enabled section in the sitemap. That is usually too much. Tag pages, category pages and search pages should usually not be in the sitemap because they generate thin or duplicate content. Author archives often should not. Paginated pages beyond the first should usually not.

SEOmatic lets you exclude sections, entry types and individual entries from the sitemap through the same cascading model as everything else. Set the defaults to what makes sense for the site and override at the entry level only when you need to.

On a high-traffic site, also think about sitemap pagination. SEOmatic produces a sitemap index by default which references individual sitemap files per section. That is the right structure once a section has more than a few thousand entries.

Robots and redirects

SEOmatic generates robots.txt from a template. Edit the template once to include disallow rules for staging URLs, admin paths and any sections you do not want indexed. Reference the sitemap URL in the same file so search engines find it without you submitting it.

SEOmatic does not handle redirects. That is a separate concern handled by the Retour plugin, also from nystudio107. Retour catches 404s, lets you remap them to live URLs and tracks which redirects are actually firing. On any site that has been through a migration, Retour pays for itself in the first month.

The common mistakes worth avoiding

Configuring meta tags at the entry level instead of the section level. Editors should override, not author from scratch. If every entry needs a custom title pattern, your section defaults are wrong.

Forgetting to set a site identity. SEOmatic has a site setup section where you define the organisation or person who owns the site, contact details, social profiles. That data flows into the JSON-LD for every page. Missing it produces incomplete structured data across the whole site.

Letting SEOmatic and a tag manager fight over the same scripts. Pick one. If you use Google Tag Manager, disable SEOmatic tracking and let GTM handle everything.

Not setting up the SEO field type for editors at all and assuming the section defaults will be enough. They usually are not. Editors need a way to override the title and description for the few entries where the default is wrong.

Leaving the development environment with indexing enabled and shipping the same configuration to production. SEOmatic supports environment-based config. Use it. Disable indexing on staging at the configuration level rather than relying on someone remembering to flick a switch.

Where SEOmatic ends and content work begins

SEOmatic produces the technical SEO output. It does not write good page titles. It does not produce useful structured data from nothing. It cannot fix thin content or weak internal linking. Everything it does is downstream of editorial decisions.

On a content site that takes SEO seriously, SEOmatic is the layer that ensures every page has the right tags, the sitemap is current and the structured data is valid. Beyond that, the work is content and information architecture, not plugin configuration.

If you want a sanity check on an existing SEOmatic configuration or you are setting up a new Craft site and want the SEO layer right from the start, Craft CMS development and rescue is where I cover this as part of the build and get in touch if you want to talk through a specific site.