SEOmatic for Craft CMS

Upon installation, SEOmatic automatically configures several features to provide immediate SEO value with minimal setup:

• SEO Previews: Added to every section with public URLs.
• Template Injection: Automatically injects title, meta, link, and JSON-LD tags into front-end templates.
• Sitemaps & Robots: Serves XML sitemaps and robots.txt (with automatic indexing prevention for non-production environments).
• Environment Indicators:
  • Front-end and Control Panel page titles include emojis to identify non-production environments.
  • Page titles are prepended with 🚧 in non-production environments.
• HTTP Headers: Adds relevant HTTP response headers to front-end and control panel URLs.
• Debug Toolbar: Includes an SEOmatic panel when Craft's debug toolbar is enabled.

SEOmatic is a turnkey SEO system for Craft CMS 5 designed to implement modern SEO best practices. It provides comprehensive, powerful, and flexible SEO management.

Important Limitation SEOmatic does not handle 404 redirects. For redirect management, it is recommended to use the Retour plugin.

SEOmatic treats elements from supported plugins (like Craft Commerce, Digital Products, Calendar, and Campaign) as first-class citizens, providing metadata, sitemaps, and CP UI for them.

If you are developing a custom Element via a plugin or module and want it to be compatible with SEOmatic, you must implement the SeoElementInterface.

SEOmatic uses Craft CMS Site Groups to determine the relationship between different sites. It treats each Site Group as a separate entity, where all sites within a single group are considered localizations (translations) of the same site.

This relationship allows SEOmatic to automatically generate SEO tags that tell search engines about alternate language versions of a page.

Example Site Group Structure:

• Primary Site Group: Contains English, Chinese, and German sites (treated as localizations of one site).
• Sister Site Group: Contains English and German sites (treated as localizations of a different site).

If your site structure does not follow this grouping logic, you must disable the automatic relationship detection in the plugin settings.

SEOmatic supports headless and Single Page Application (SPA) architectures. You can retrieve the metadata required for a specific route either as a structured array or as DOM elements ready to be inserted into your application's head.

For technical implementation details, refer to the Headless SPA API section in the advanced documentation.

SEOmatic uses configuration files to define meta bundles (e.g., categorymeta, entrymeta, globalmeta).

How to customize:

1. Locate the vendor/nystudio107/seomatic/src/seomatic-config directory.
2. Copy the desired configuration files to your Craft config/ directory.
3. SEOmatic will prioritize files in config/ over its internal defaults.

Important Limitations:

• These files are only used during initial creation of a meta bundle (e.g., upon plugin installation or when a new Section, Category Group, or Commerce Product Type is created).
• Changes to these files will not affect existing bundles once they have been created.
• To force SEOmatic to re-read your config settings for existing bundles, you must increment the bundleVersion setting in Bundle.php.

SEOmatic allows you to manage common tracking scripts (Google Analytics, Google Tag Manager, Facebook Pixel, etc.) directly from the Craft CMS control panel.

Environment Behavior:

• Live Production: Scripts are included on front-end pages when the SEOmatic environment is set to live.
• Local Development: If devMode is enabled in Craft, the SEOmatic environment is automatically set to local, and tracking scripts are not included by default to prevent polluting your analytics data during development.

SEOmatic uses a layered approach to determine SEO metadata, known as the meta cascade. When a Craft request is made, SEOmatic examines the route and layers settings in the following order of precedence (from lowest to highest):

1. Global SEO settings: The base configuration for the entire site.
2. Content SEO settings: Settings corresponding to a specific Craft CMS Section.
3. SEO Settings fields: Individual field values provided by content authors within a specific entry/content item.

This hierarchy allows for 'Healthy SEO by default,' where metadata is automatically generated from existing content models, while still allowing for granular overrides by authors or developers.

Upon installation, SEOmatic begins working immediately without requiring manual template code. It automatically performs the following tasks:

• Metadata Rendering: Renders SEO metadata on your web pages.
• Sitemap Generation: Creates sitemaps for all Craft CMS Sections, Category Groups, and Commerce Product Types that have public URLs.

All settings are multi-site aware, meaning you can configure unique SEO settings for different site and language combinations.