Configuring SEOmatic ​

As soon as you install SEOmatic, it automatically will render metadata on your web pages, and create sitemaps for all of your Sections, Category Groups, and Commerce Product Types that have public URLs. You don’t need to add any template code for this to happen.

All of SEOmatic’s settings are multi-site aware, allowing you to have different settings for each site/language combination.

For SEOmatic to be truly useful, you need to configure it so that it knows where to pull SEO content from.

N.B. Please ensure that you set up your Multi-Environment Config Settings if you will be using SEOmatic across multiple environments.

Dashboard ​

The Dashboard gives you an overview of how fully set up your SEO setting in SEOmatic are, for Global SEO, Content SEO, and Site Settings.

Click on any of the graphs to jump to the section in question to fill things out in more detail.

Global SEO ​

Global SEO is where you set all of the default site-wide settings. The Copy Settings From: dropdown allows you to easily copy settings from one site to another.

SEOmatic allows you to have different Global SEO settings on a per-site basis.

General ​

Best practices for modern SEO are for the meta information to reflect your content, so you should set up the fields that SEOmatic pulls the SEO Title, SEO Description, and SEO Image from.

Twitter ​

By default, the Twitter and Facebook settings will mirror what you set in the General section, but you can customize them to your heart’s content.

Facebook ​

By default, the Twitter and Facebook settings will mirror what you set in the General section, but you can customize them to your heart’s content.

Robots ​

A robots.txt file is a file at the root of your site that indicates those parts of your site you don’t want accessed by search engine crawlers. The file uses the Robots Exclusion Standard, which is a protocol with a small set of commands that can be used to indicate access to your site by section and by specific kinds of web crawlers (such as mobile crawlers vs desktop crawlers).

You shouldn’t need to edit the default robots.txt Template, but you can if you like.

SEOmatic automatically handles requests for /robots.txt. For this to work, make sure that you do not have an actual robots.txt file in your web/ folder (because that will take precedence).

If you are running Nginx, make sure that you don’t have a line like:

location = /robots.txt  { access_log off; log_not_found off; }

...in your config file. A directive like this will prevent SEOmatic from being able to service the request for /robots.txt. If you do have a line like this in your config file, just comment it out, and restart Nginx with sudo nginx -s reload.

The View robots.txt button lets you view your rendered robots.txt.

Humans ​

Humans.txt is an initiative for knowing the people behind a site. It’s a text file that contains information about the different people who have contributed to building the site. By adding a text file, you can prove your authorship (not your property) in an external, fast, easy and accessible way.

Feel free to edit the default humans.txt Template to your heart’s content.

The View humans.txt button lets you view your rendered humans.txt.

Ads ​

The ads.txt project is simple: Increase transparency in the programmatic advertising ecosystem. Ads.txt stands for Authorized Digital Sellers and is a simple, flexible and secure method that publishers and distributors can use to publicly declare the companies they authorize to sell their digital inventory.

Feel free to edit the default ads.txt Template to your heart’s content.

The View ads.txt button lets you view your rendered ads.txt.

Security ​

The security.txt defines a standard to help organizations define the process for security researchers to disclose security vulnerabilities securely

Feel free to edit the default security.txt Template to your heart’s content.

The View security.txt button lets you view your rendered security.txt.

Global SEO Control Panel Fields ​

The fields in the Control Panel Global SEO settings are parsed as Twig object templates, so in addition to plain old text, you can also put single and double bracket Twig expressions.

SEOmatic fields are also parsed for aliases, and in Craft 3.1, for environment variables as well.

This is entirely optional; in typical usage the controls you have in the Control Panel for pulling from other fields will be all you need. But the ability is there if you need it.

For example, the following will output the contents of the companyInfo field from the siteInfo Global:

{{ siteInfo.companyInfo }}

You can even do complex expressions, such as the following which outputs the first field that isn’t empty, or a default text:

{{ siteInfo.companyInfo ??? siteInfo.companySummary ??? "Some default text" }}

The above uses the ??? empty coalesce operator that comes with SEOmatic; check out SEOmatic’s ??? Empty Coalesce operator for details.

You can also access SEOmatic global variables (discussed below):

{seomatic.meta.seoTitle}

Normal Twig double bracket syntax is supported too:

{{ seomatic.meta.seoTitle }}

The single bracket syntax is just a shortcut, and provided for backwards compatibility with previous versions of SEOmatic.

Content SEO ​

Content SEO is where you can configure each Section, Category Group and Commerce Product Type that has public URLs. You’ll see a list of all of your Sections, Category Groups, and Commerce Product Types that have public URLs, with status indicators letting you know what has been configured for each.

SEOmatic allows you to have different Content SEO settings on a per-site basis, and also on a per-Entry Type basis.

Click on a Section, Category Group, or Commerce Product Type name to edit its settings.

General ​

Best practices for modern SEO are for the meta information to reflect your content, so you should set up the fields that SEOmatic pulls the SEO Title, SEO Description, and SEO Image from.

Twitter ​

By default, the Twitter and Facebook settings will mirror what you set in the General section, but you can customize them to your heart’s content.

Facebook ​

By default, the Twitter and Facebook settings will mirror what you set in the General section, but you can customize them to your heart’s content.

Sitemap ​

SEOmatic automatically creates a sitemap index for each of your Site Groups. This sitemap index points to individual sitemaps for each of your Sections, Category Groups, and Commerce Product Types.

Instead of one massive sitemap that must be updated any time anything changes, only the sitemap for the Section, Category Group, or Commerce Product Type will be updated when something changes in it.

SEOmatic can automatically include files such as .pdf, .xls, .doc and other indexable file types in Asset fields or Asset fields in matrix or Neo blocks.

In addition, SEOmatic can automatically create Image sitemaps and Video sitemaps from images & videos in Asset fields or Asset fields in matrix or Neo blocks

Sitemap Indexes are automatically submitted to search engines whenever a new Section, Category Group, or Commerce Product Type is added.

Section Sitemaps are automatically submitted to search engines whenever a new Element in that Section, Category Group, or Commerce Product Type is added.

Sitemap Generation ​

Because XML sitemaps can be quite time-intensive to generate as the number of entries scales up, SEOmatic creates your sitemaps via a Queue job, and caches the result. The cache is automatically broken whenever something in that sitemap is changed, and a new Queue job is created to regenerate it.

If runQueueAutomatically is set to false in General Config Settings the Queue job to create the sitemap will not be run during the http request for the sitemap. You’ll need to run it manually via whatever means you use to run the Queue.

Normally SEOmatic will regenerate the sitemap for a Section, Category Group, or Product any time you save an element. However, if you are importing a large number of elements, or prefer to regenerate the sitemap manually you can set disable the Regenerate Sitemaps Automatically option in SEOmatic’s Plugin Settings.

You can then regenerate the sitemap via CLI. This will regenerate all sitemaps:

./craft seomatic/sitemap/generate

You can also limit it to a specific Section, Category Group, or Product handle:

./craft seomatic/sitemap/generate --handle=blog

...or you can regenerate all sitemaps for a specific siteId:

./craft seomatic/sitemap/generate --siteId=1

...or both:

./craft seomatic/sitemap/generate --handle=blog --siteId=1

N.B.: If you do disable Regenerate Sitemaps Automatically sitemaps will not be updated unless you do so manually via the CLI, or clear SEOmatic’s sitemap caches via Utilities->Clear Caches.

Additional Sitemaps ​

If you have custom sitemaps that are not in the CMS, you can manually add them to their own Sitemap Index via Site Settings → Sitemap.

You can also add to it via a plugin:

use nystudio107\seomatic\events\RegisterSitemapsEvent;
use nystudio107\seomatic\models\SitemapIndexTemplate;
use yii\base\Event;
Event::on(SitemapIndexTemplate::class, SitemapIndexTemplate::EVENT_REGISTER_SITEMAPS, function(RegisterSitemapsEvent $e) {
    $e->sitemaps[] = [
        'loc' => $url,
        'lastmod' => $lastMod,
    ];
});

Additional Sitemap URLs ​

If you have custom URLs that are not in the CMS, you can manually add them to their own Sitemap Index via Site Settings → Sitemap.

You can also add to it via a plugin:

use nystudio107\seomatic\events\RegisterSitemapUrlsEvent;
use nystudio107\seomatic\models\SitemapCustomTemplate;
use yii\base\Event;
Event::on(SitemapCustomTemplate::class, SitemapCustomTemplate::EVENT_REGISTER_SITEMAP_URLS, function(RegisterSitemapUrlsEvent $e) {
    $e->sitemaps[] = [
         'loc' => $url,
         'changefreq' => $changeFreq,
         'priority' => $priority,
         'lastmod' => $lastMod,
     ];
 });

Content SEO Control Panel Fields ​

The fields in the Control Panel Content SEO settings are parsed as Twig object templates, so in addition to plain old text, you can also put single and double bracket Twig expressions.

SEOmatic fields are also parsed for aliases, and in Craft 3.1, for environment variables as well.

This is entirely optional; in typical usage the controls you have in the Control Panel for pulling from other fields will be all you need. But the ability is there if you need it.

For example, the following will output the contents of the description field from the current Entry:

{entry.description}

Normal Twig double bracket syntax is supported too:

{{ entry.description }}

The single bracket syntax is just a shortcut, and provided for backwards compatibility with previous versions of SEOmatic.

The same applies to any SEOmatic global variables (discussed below):

{seomatic.meta.seoTitle}

Is the same as:

{{ seomatic.meta.seoTitle }}

You can even do complex expressions, such as the following which outputs the first field that isn’t empty, or a default text:

{{ entry.description ??? entry.summary ??? "Some default text" }}

The above uses the ??? empty coalesce operator that comes with SEOmatic; check out SEOmatic’s ??? Empty Coalesce operator for details.

Site Settings ​

Identity ​

These Site Identity settings are used to globally define the identity and ownership of the site.

They are used in combination with the SEO Template Meta settings to generate JSON-LD microdata.

The Site Owner type determines the JSON-LD schema that will be used to identity the site to search engines.

Leave any fields blank that aren’t applicable or which you do not want as part of the SEO schema.

Creator ​

These Site Creator settings are used to globally define the creator (such as the agency or freelancer) of the site.

They are used in combination with the SEO Template Meta settings to generate JSON-LD microdata as well as the humans.txt file.

The Site Creator type determines the JSON-LD schema that will be used to identity the site to search engines.

Leave any fields blank that aren’t applicable or which you do not want as part of the SEO schema.

Social Media ​

The social media settings connect your site to its other points of pressence on the internet. They also facilitate attaching your branding to social media posts via Twitter Cards and Facebook OpenGraph.

Sitemap ​

SEOmatic will automatically create a sitemap for each of your sections, but if you have additional sitemaps or individual URLs that are outside of the CMS that you want to include, you can add them here.

Miscellaneous ​

Miscellaneous site-wide SEO settings.

Tracking Scripts ​

None of the Tracking Scripts are included on the page unless the SEOmatic environment is set to live production. If devMode is enabled, the SEOmatic environment is automatically set to local development.

Google Analytics ​

Google Analytics gives you the digital analytics tools you need to analyze data from all touchpoints in one place, for a deeper understanding of the customer experience. You can then share the insights that matter with your whole organization. Learn More

To include the Google Analytics script despite devMode being enabled, you can do:

{% do seomatic.script.get('googleAnalytics').include(true) %}

Google gtag.js ​

The global site tag (gtag.js) is a JavaScript tagging framework and API that allows you to send event data to AdWords, DoubleClick, and Google Analytics. Instead of having to manage multiple tags for different products, you can use gtag.js and more easily benefit from the latest tracking features and integrations as they become available. Learn More

To include the gtag script despite devMode being enabled, you can do:

{% do seomatic.script.get('gtag').include(true) %}

Google Tag Manager ​

Google Tag Manager is a tag management system that allows you to quickly and easily update tags and code snippets on your site. Once the Tag Manager snippet has been added to your site or mobile app, you can configure tags via a web-based user interface without having to alter and deploy additional code. Learn More

You can set the dataLayer passed in to Google Tag Manager via Twig:

{% do seomatic.script.get('googleTagManager').dataLayer({
    'woof': 'bark'
}) %}

To include the Google Tag Manager script despite devMode being enabled, you can do:

{% do seomatic.script.get('googleTagManager').include(true) %}

Facebook Pixel ​

The Facebook pixel is an analytics tool that helps you measure the effectiveness of your advertising. You can use the Facebook pixel to understand the actions people are taking on your site and reach audiences you care about. Learn More

To include the Facebook Pixel script despite devMode being enabled, you can do:

{% do seomatic.script.get('facebookPixel').include(true) %}

LinkedIn Insight ​

The LinkedIn Insight Tag is a lightweight JavaScript tag that powers conversion tracking, retargeting, and web analytics for LinkedIn ad campaigns.

To include the LinkedIn Insight script despite devMode being enabled, you can do:

{% do seomatic.script.get('linkedInInsight').include(true) %}

HubSpot ​

If you’re not hosting your entire site on HubSpot, or have pages on your site that are not hosted on HubSpot, you’ll need to install the HubSpot tracking code on your non-HubSpot pages to capture those analytics.

To include the HubSpot script despite devMode being enabled, you can do:

{% do seomatic.script.get('hubSpot').include(true) %}

Plugin Settings ​

The Plugin Settings lets you control various SEOmatic settings globally (across all sites/languages).

General Plugin Settings ​

• Plugin name - This is the name that will be used for the plugin everywhere it is referenced in the Control Panel GUI
• Automatic Render Enabled - Controls whether SEOmatic will automatically render metadata on your pages. If you turn this off, you will need to manually render the metadata via seomatic.tag.render(), seomatic.link.render(), etc. You can selectively disable rendering via Twig with {% do seomatic.config.renderEnabled(false) %}
• Sitemaps Enabled - Controls whether SEOmatic will automatically render frontend sitemaps for your site.
• Regenerate Sitemaps Automatically - Controls whether sitemaps will automatically be regenerated when entries are saved.
• Submit Sitemap Changes - Should sitemaps be submitted to search engines automatically whenever there are changes?
• Include Homepage in Breadcrumbs - Should the homepage be included in the generated Breadcrumbs JSON-LD?
• Manually Set SEOmatic Environment - If off, SEOmatic will automatically attempt to determine the current environment. Turn this on to manually set the environment.
• Environment - The server environment, either live, staging, or local. If devMode is on, SEOmatic will override this setting to local Development. This setting controls whether certain things render; for instance only in the live production environment will Google Analytics and other tracking tags send analytics data. SEOmatic also automatically sets the robots tag to none for everything but the live production environment.

Appearance Plugin Settings ​

• Display Sidebar SEO Preview - Controls whether to display the Google, Twitter, and Facebook social media previews in the sidebar on entry. Category, and product pages.
• Add Social Media Preview Target - Controls whether to add the Google, Twitter, Facebook, etc. social media previews as a Preview Target.
• SEO Preview Sites - The social media platforms that should be displayed in the SEO Preview

Title Plugin Settings ​

• devMode <title> prefix - If devMode is on, prefix the <title> with this string
• Control Panel <title> prefix - Prefix the Control Panel <title> with this string
• devMode Control Panel <title> prefix - If devMode is on, prefix the Control Panel <title> with this string
• Separator Character - The separator character to use for the <title> tag
• Max SEO Title Length - The max number of characters in the <title> tag; anything beyond this will be truncated on word boundaries
• Max SEO Description Length - The max number of characters in the meta description tag
• Truncate Title Tags - Should Title tags be truncated at the max length, on word boundaries?
• Truncate Description Tags - Should Description tags be truncated at the max length, on word boundaries?

Tags Plugin Settings ​

• Add hreflang Tags - Controls whether SEOmatic will automatically add hreflang and og:locale:alternate tags.
• Include x-default hreflang Tag - Controls whether SEOmatic will automatically include an x-default hreflang tag
• Include Paginated hreflang Tags - Controls whether SEOmatic will automatically include hreflang tags on paginated pages
• Generator Enabled - Controls whether SEOmatic will include the meta generator tag and X-Powered-By header
• HTTP Headers Enabled - Controls whether SEOmatic will automatically add X-Robots-Tag, canonical, & Referrer-Policy to the http response headers.
• Nonces for <script> tags - Whether SEOmatic should automatically add script-src Content Security Policy (CSP) nonces to <script> tags (including JSON-LD)
• Fixed script-src Content Security Policies - Fixed Content Security Policy (CSP) script-src policies that should be added before the Nonces

Endpoints Plugin Settings ​

• Meta Container Endpoint Access - Whether anonymous access to the Meta Container endpoint should be allowed
• JSON-LD Endpoint Access - Whether anonymous access to the JSON-LD endpoint should be allowed

Advanced Plugin Settings ​

• Site Groups define logically separate sites - If you are using Site Groups to logically separate 'sister sites’, turn this on.
• Lowercase Canonical URL - Should the Canonical URL be automatically lower-cased?
• Site URL Override - SEOmatic uses the Craft siteUrl to generate the external URLs. If you are using it in a non-standard environment, such as a headless GraphQL or ElementAPI server, you can override what it uses for the siteUrl.
• Meta Cache Duration - The duration of the SEOmatic meta cache. The default Unlimited setting is typically desired, as SEOmatic will break the cache as needed. If devMode is on, caches last 30 seconds.

Multi-Environment Config Settings ​

SEOmatic does different things depending on the SEOmatic environment it is running in. This is a separate setting from your Craft environment, because you can name those anything you like.

SEOmatic needs some way to map what you call your local, staging, and production environments to a normalized representation.

In local dev and staging environments, the following things change:

1. <meta name="robots"> tags are rendered with none to prevent Google from indexing the pages
2. The robots.txt page is rendered to disallow all indexing
3. No scripts are loaded on the page, to prevent errant data being sent to endpoints
4. Because the <meta name="robots"> tag is set to none, the <link rel="canonical"> is not rendered

You can override all of these things as you see fit, but they are automatically changed in this manner to help protect you from having pages indexed or sending data from environments where you should not.

If you’re using a multi-environment config, you can map your environment settings using SEOmatic’s config.php something like this:

<?php 
return [
    // The public-facing name of the plugin
    'pluginName' => 'SEOmatic',

    // Should SEOmatic render metadata?
    'renderEnabled' => true,

    // Should SEOmatic render frontend sitemaps?
    'sitemapsEnabled' => true,

    // Should sitemaps be regenerated automatically?
    'regenerateSitemapsAutomatically' => true,

    // Should sitemaps be submitted to search engines automatically whenever there are changes?
    'submitSitemaps' => true,

    // Should SEOmatic add to the http response headers?
    'headersEnabled' => true,

    // The server environment, either `live`, `staging`, or `local`
    'environment' => 'live',

    // Should SEOmatic display the SEO Preview sidebar?
    'displayPreviewSidebar' => true,

    // Should SEOmatic add a Social Media Preview Target?
    'socialMediaPreviewTarget' => true,

    // The social media platforms that should be displayed in the SEO Preview sidebar
    'sidebarDisplayPreviewTypes' => [
        'google',
        'twitter',
        'facebook'
    ],

    // Should SEOmatic display the SEO Analysis sidebar?
    'displayAnalysisSidebar' => true,

    // If `devMode` is on, prefix the <title> with this string
    'devModeTitlePrefix' => '&#x1f6a7; ',

     //  Prefix the Control Panel <title> with this string
    'cpTitlePrefix' => '&#x2699; ',

    // If `devMode` is on, prefix the Control Panel <title> with this string
    'devModeCpTitlePrefix' => '&#x1f6a7;&#x2699; ',

    // The separator character to use for the `<title>` tag
    'separatorChar' => '|',

    // The max number of characters in the `<title>` tag
    'maxTitleLength' => 70,

    // The max number of characters in the `<meta name="description">` tag
    'maxDescriptionLength' => 155,

    // Site Groups define logically separate sites
    'siteGroupsSeparate' => true,

    // Whether to dynamically include the hreflang tags
    'addHrefLang' => true,

    // Whether to dynamically include the `x-default` hreflang tags
    'addXDefaultHrefLang' => true,

    // Whether to dynamically include hreflang tags on paginated pages
    'addPaginatedHreflang' => true,

    // Should the Canonical URL be automatically lower-cased?
    'lowercaseCanonicalUrl' => true,

    // Should the meta generator tag and X-Powered-By header be included?
    'generatorEnabled' => true,

    // SEOmatic uses the Craft `siteUrl` to generate the external URLs.  If you
    // are using it in a non-standard environment, such as a headless GraphQL or
    // ElementAPI server, you can override what it uses for the `siteUrl` below.
    'siteUrlOverride' => '',

    // The duration of the SEOmatic meta cache in seconds. Null means always cached until explicitly broken
    // If devMode is on, caches last 30 seconds.
    'metaCacheDuration' => null,

    // Determines whether the meta container endpoint should be enabled for anonymous frontend access
    'enableMetaContainerEndpoint' => false,

    // Determines whether the JSON-LD endpoint should be enabled for anonymous frontend access
    'enableJsonLdEndpoint' => false,

    // SeoElementInterface[] The default SeoElement type classes
    'defaultSeoElementTypes' => [
    ],
];

Just copy the config.php to your Craft config/ directory as seomatic.php and you can configure the settings in a multi-environment friendly way. See the Craft Environments page for details, and N.B.:

The '*' key is required here so Craft knows to treat it as a multi-environment key, but the other keys are up to you

This is how you can make your multi-environment nomenclature to SEOmatic’s. This works exactly like Craft’s multi-environment config files such as general.php and db.php. See SEOmatic’s config.php for details.

Access Permissions ​

SEOmatic allows you to restrict access to various parts of the plugin based on User Group Permissions:

• Dashboard
• Edit Global Meta
  • General
  • Twitter
  • Facebook
  • Robots
  • Humans
  • Ads
• Edit Content SEO
  • General
  • Twitter
  • Facebook
  • Sitemap
• Edit Site Settings
  • Identity
  • Creator
  • Social Media
  • Miscellaneous
• Edit Tracking Scripts
  • Google Analytics
  • Google gtag.js
  • Google Tag Manager
  • Facebook Pixel
• Edit Plugin Settings

Brought to you by nystudio107