Slack 

Join the #yoast-seo-for-typo3 channel on the TYPO3 Slack.

If you are not registered yet, find out more about how to join.

Github 

Found a bug in the extension? Please report this in our Github repository.

Access rights 

Through the "Access lists" of backend users and groups it's possible to configure access for:

• All the Yoast SEO fields within pages
• The backend modules
• The Dashboard widgets

Enable snippet preview on specific page types 

By default, the snippet preview is only shown on pages with doktype 1 (Standard page) and 6 (Backend user section). You can add your own doktypes like the example below by adding a doktype to the $GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['yoast_seo']['allowedDoktypes'] array in the ext_localconf.php of your own extension.

$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['yoast_seo']['allowedDoktypes']['blog'] = 137;

The key can be any unique string. It is only used to identify the doktype as a developer. The value contains the numeric value of the doktype.

Disable snippet preview with PageTSConfig 

Sometimes only a check on doktype isn't enough for disabling the snippet preview. For example if you want to hide the snippet preview on detail pages of for example a news item, you need more than a check on a doktype. That is why you can also disable the snippet preview based on PageTSConfig. Below is an example of how to hide the snippet preview if the page is a subpage of page with id 4.

[4 in tree.rootLineParentIds]
    mod.web_SeoPlugin {
        disableSnippetPreview = 1
    }
[global]

Basic auth configuration 

For environments which are protected by Basic auth, it's possible to set username and password through $GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['yoast_seo']['previewSettings']['basicAuth']

$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['yoast_seo']['previewSettings']['basicAuth'] = [
    'username' => 'authUsername',
    'password' => 'authPassword'
];

BreadcrumbList 

The output for the type BreadcrumbList is provided by the provider key breadcrumb.

An example output for this provider is:

[
   {
      "@context":"https://www.schema.org",
      "@type":"BreadcrumbList",
      "itemListElement": [
         {
            "@type": "ListItem",
            "position": 1,
            "item": {
               "@id": "https://example.com/",
               "name": "Example"
            }
         },
         {
            "@type": "ListItem",
            "position": 2,
            "item": {
               "@id": "https://example.com/test-page",
               "name": "Test page"
            }
         }
      ]
   }
]

Possible configuration options:

WebSite 

The output for the type WebSite is provided by the provider key site.

An example output for this provider is:

[
    {
        "@context": "https://www.schema.org",
        "@type": "WebSite",
        "url": "https://example.com/",
        "name": "Example"
    }
]

This provider does not have any configurable options.

Disabling provider(s) 

If you want to disable a certain provider, you can do this by unsetting the provider key through typoscript. Example:

config.structuredData.providers.breadcrumb >

Custom provider 

It is possible to register a custom provider. For this, it's necessary to create a class which implements the StructuredDataProviderInterface and provides a method getData which returns a multidimensional array. An example:

<?php
namespace Vendor\Package\StructuredData;

class CustomStructuredDataProvider implements \YoastSeoForTypo3\YoastSeo\StructuredData\StructuredDataProviderInterface
{
    public function getData(): array
    {
        return [
            [
                '@context' => 'https://schema.org',
                '@type' => 'Person',
                'name' => 'John Doe',
                'email' => 'john@doe.com'
            ]
        ];
    }
}

After you have created the class, you can add it to the provider-list by registering it through typoscript:

config.structuredData.providers {
    custom {
        provider = Vendor\Package\StructuredData\CustomStructuredDataProvider
    }
}

If you want to have custom configuration with your provider, you can add a method setConfiguration which will be automatically called if available.

Example:

protected $configuration = [];

public function setConfiguration(array $configuration): void
{
    $this->configuration = $configuration;
}

Structured data provider ordering 

If you want to order the rendering of the providers, you can make use of the before and after settings.

If, for example, you want your custom provider to be rendered before breadcrumb and after site:

config.structuredData.providers {
    custom {
        provider = Vendor\Package\StructuredData\CustomStructuredDataProvider
        before = breadcrumb
        after = site
    }
}

Typoscript provider 

It is possible to configure structured data through typoscript.

This is done through the config.structuredData.data object. The type and context keys do not need a @ and stdWrap is available on all keys.

An example for this configuration:

config.structuredData.data {
    10 {
        context = https://schema.org
        type = Person
        name = TEXT
        name.data = field:author
        email = TEXT
        email.data = field:author_email
    }
}

Inclusive Language analysis 

Feature Toggle

yoastSeoInclusiveLanguage

Default

false

Description

Enables the Inclusive Language analysis, which checks your content for non-inclusive language and suggests more inclusive alternatives. When enabled, the analysis appears alongside the Readability and SEO analysis in the page module and page properties.

To enable, add the following to your config/system/additional.php (or typo3conf/system/additional.php for non-Composer setups):

$GLOBALS['TYPO3_CONF_VARS']['SYS']['features']['yoastSeoInclusiveLanguage'] = true;

Disable all caches on Yoast preview requests 

Feature Toggle

yoastSeoDisableAllCachesOnPreviewRequest

Default

false

Description

Disables all TYPO3 caches for frontend requests that originate from Yoast. When enabled, the noCache request attribute is set on every validated Yoast request. This should only be necessary for edge cases where hidden pages could end up in certain caches (f.e. a custom menu cache).

To enable, add the following to your config/system/additional.php (or typo3conf/system/additional.php for non-Composer setups):

$GLOBALS['TYPO3_CONF_VARS']['SYS']['features']['yoastSeoDisableAllCachesOnPreviewRequest'] = true;

Required: adding PageTsconfig preview configuration 

One important thing to know is that the snippet preview of records other than pages, only works when you have set a proper preview link. This is needed for both of the solutions above. The only thing you need to do is set some PageTsconfig. More information about the configuration of the preview links can be found in the documentation.

An example configuration of the preview links for EXT:news records is:

TCEMAIN.preview {
    tx_news_domain_model_news {
        previewPageId = <YOUR_DETAIL_PAGE_ID_HERE>
        useCacheHash = 1
        useDefaultLanguageRecord = 0
        fieldToParameterMap {
                uid = tx_news_pi1[news_preview]
        }
        additionalGetParameters {
                tx_news_pi1.controller = News
                tx_news_pi1.action = detail
        }
    }
}

What does the automatic functionality do? 

By using the automatic functionality the following will be added to your records:

• Backend:

  • Fields of the core SEO extension:

    • SEO title
    • Robots: Index this page, Follow this page
    • Opengraph fields: Title, Description, Image
    • Twitter fields: Title, Description, Image, Card
    • Canonical link
    • Sitemap: Change frequency, Priority

  • Functionality of Yoast SEO:

    • Snippet preview
    • Title and Description progress bar
    • Readability Analysis
    • SEO Analysis
    • Inclusive Language Analysis (when enabled via Feature Toggle)
    • Focus keyword
    • Advanced robots: Image index, Archive, Snippet

• Frontend:

  • Metatag tags:

    • Description
    • Opengraph
    • Twitter
    • Robots

  • Canonical generation
  • Page title based on SEO Title and Title field

Configuration for a record 

To get all the functionality mentioned above you only have to set the table name and the GET parameters on which it responds to. This should be placed in a file within Configuration/TCA/Overrides of your extension (f.e. sitepackage):

<?php

\YoastSeoForTypo3\YoastSeo\Utility\RecordUtility::configureForRecord('tx_extension_record')
     ->setGetParameters([
         ['tx_extension_pi1', 'record']
     ]);

This will automatically set the TCA, Database fields and activate the frontend functionality.

Configuration options 

The method configureRecord returns an object which has the following methods:

->setGetParameters([
   ['tx_extension_pi1', 'record'],
   ['tx_extension_pi1', 'record_preview']
])

->setOverrideTca([
   'columns' => [
      'seo_title' => [
         'config' => [
            'max' => 100
         ]
      ]
   ]
])

Example with EXT:news 

EXT:news has his own sitemap fields and has multiple GET parameters to respond to. The basic configuration can be:

\YoastSeoForTypo3\YoastSeo\Utility\RecordUtility::configureForRecord('tx_news_domain_model_news')
     ->setGetParameters([
         ['tx_news_pi1', 'news'],
         ['tx_news_pi1', 'news_preview']
     ])
     ->setSitemapFields(false)
     ->setFieldsPosition('after:bodytext');

Adding PageTsconfig 

Make sure to add the needed PageTsconfig mentioned in Other Plugins

How to integrate in other plugins 

By default the SEO and Readability analysis is only done on pages. When enabled via the Feature Toggle yoastSeoInclusiveLanguage, the Inclusive Language analysis is also available (see Content Analysis). If you want more type of records to use the SEO functions from Yoast SEO you have to add some fields to the TCA.

$llPrefix = 'LLL:EXT:yoast_seo/Resources/Private/Language/BackendModule.xlf:';
\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addTCAcolumns(
    'tx_news_domain_model_news',
    [
        'tx_yoastseo_snippetpreview' => [
            'label' => $llPrefix . 'snippetPreview',
            'exclude' => true,
            'displayCond' => 'REC:NEW:false',
            'config' => [
                'type' => 'none',
                'renderType' => 'snippetPreview',
                'settings' => [
                    'titleField' => 'alternative_title',
                    'descriptionField' => 'description'
                ]
            ]
        ],
        'tx_yoastseo_readability_analysis' => [
            'label' => $llPrefix . 'analysis',
            'exclude' => true,
            'config' => [
                'type' => 'none',
                'renderType' => 'readabilityAnalysis'
            ]
        ],
        'tx_yoastseo_focuskeyword' => [
            'label' => $llPrefix . 'seoFocusKeyword',
            'exclude' => true,
            'config' => [
                'type' => 'input',
            ]
        ],
        'tx_yoastseo_focuskeyword_analysis' => [
            'label' => $llPrefix . 'analysis',
            'exclude' => true,
            'config' => [
                'type' => 'none',
                'renderType' => 'focusKeywordAnalysis',
                'settings' => [
                    'focusKeywordField' => 'tx_yoastseo_focuskeyword',
                ]
            ]
        ],

    ]
);

In the example above, you see we define four fields for in this case the EXT:news records.

The first field with renderType snippetPreview, is the field for the snippet preview. In the settings section, you have to define which fields contains the SEO title and the description. The snippet preview will use these fields to show you your search result will look like. Make sure the fields that are set, do exist. This field doesn't need a column in the database.

The second field doesn't need much configuration. Just add a field with renderType readabilityAnalysis to have the readabilityAnalysis in your record. This field also doesn't need a column in the database.

To have your content checked for SEO, you have to set a focus keyword, so we need to add that field as well. This can be a simple text field. This is the only field that needs a column in the database. Make sure you add this field to the database table for your records. For the news table this would be the following within the ext_tables.sql of your extension:

CREATE TABLE tx_news_domain_model_news (
    tx_yoastseo_focuskeyword varchar(100) DEFAULT '' NOT NULL,
);

To show the focus keyword analysis, we need to add a field of renderType focusKeywordAnalysis. In the settings section you have to define the field you have created with the focus keyword. This field also doesn't need a column in the database.

Adding PageTsconfig 

Make sure to add the needed PageTsconfig mentioned in Other Plugins

Where can I find the snippet preview? 

The snippet preview is located in 2 places.

By default it is rendered within the page module above your content: |img-snippetpreview-page|

You can also find the snippet preview within the SEO tab of the page properties: |img-snippetpreview-properties|

What information is used for the snippet preview? 

Can I disable the snippet preview? 

There are two ways to disable the snippet preview within the page module:

|img-snippetpreview-hide-page|

|img-snippetpreview-hide-global|

Can I disable the analysis? 

You can disable the Yoast SEO analysis (readability, SEO and inclusive language scoring) independently from the snippet preview.

• The readability and SEO score indicators are hidden
• No analysis is calculated or saved
• Existing scores and prominent words for the page are removed
• The snippet preview can remain visible independently

Where can I find the Facebook preview? 

The Facebook preview is located in the Social media tab of the page properties, inside the Open Graph palette. It is rendered directly above the OpenGraph fields.

|img-facebook-preview|

What fields are used for the Facebook preview? 

How does the live preview work? 

The preview updates in real-time as you type in the OpenGraph fields. Any changes to the title, description, or image are reflected immediately in the preview, so you can see exactly how your page will look when shared on social media before saving.

Where can I find the X/Twitter preview? 

The X/Twitter preview is located in the Social media tab of the page properties, inside the Twitter Cards palette. It is rendered directly above the Twitter Card fields.

|img-twitter-preview|

What fields are used for the X/Twitter preview? 

How does the live preview work? 

The preview updates in real-time as you type in the Twitter Card fields. Any changes to the title, description, image, or card type are reflected immediately in the preview, so you can see exactly how your page will look when shared on X before saving.

Where can I find the analysis? 

Inclusive Language analysis 

The Inclusive Language analysis checks your content for non-inclusive language and suggests more inclusive alternatives. This analysis is not enabled by default.

To enable the Inclusive Language analysis, you need to activate the TYPO3 Feature Toggle yoastSeoInclusiveLanguage. You can do this by adding the following to your config/system/additional.php (or typo3conf/system/additional.php for non-Composer setups):

$GLOBALS['TYPO3_CONF_VARS']['SYS']['features']['yoastSeoInclusiveLanguage'] = true;

Once enabled, the Inclusive Language analysis will appear alongside the Readability and SEO analysis in the page module and page properties.

Disabling the analysis 

You can disable the analysis for specific pages. When analysis is disabled, the readability and SEO score indicators are hidden, no analysis is calculated, and existing scores and prominent words are removed. The snippet preview can remain visible independently.

To disable the analysis on a specific page, check "Disable analysis" in the Advanced settings of the SEO tab in the page properties.

Insights 

An example of a prominent words list:

|img-insights|

Focus keyphrase 

Within this field you set the main focus of the page, for example "bike".

The value of this field will be taken into account with the content analysis, to make sure your content matches what you want to focus on.

Synonyms 

Related keyphrases 

|img-focus-related|

Cornerstone content 

This shows a list of all the pages marked as "Cornerstone content" within your installation.

Pages without meta description 

Orphaned content 

Local environment with DDEV 

In this repository we added a DDEV setup so you can easily test your contributions in all the TYPO3 versions the extension should work with.

First of all, make sure you have installed DDEV and Docker. See the DDEV documentation how to do that. After you have installed DDEV, run the following command in the root of this repository.

ddev start

After the setup is started, you can use the following command to make sure all installations are up and running.

ddev install-all

When the script is finished, you can go to https://yoast-seo.ddev.site and check the TYPO3 installations that are available to test your work.

ddev rm -O -R

rm -rf .Build/v12 .Build/v13 .Build/v14

Prerequisites 

• Node.js v22.20.0 (see Build/typescript/.nvmrc)
• Yarn package manager

Install dependencies:

cd Build/typescript
yarn install

Commands 

cd Build/typescript
yarn build

cd Build/typescript
yarn dev

TypeScript configuration 

The tsconfig.json maps @yoast/yoast-seo-for-typo3/* to ./src/* via path aliases, matching the TYPO3 JavaScript module import map configured in Configuration/JavaScriptModules.php.

Output structure 

The compiler outputs flat .js files and subdirectories into Resources/Public/JavaScript/.

Code style 

The project uses Prettier. Configuration is in Build/typescript/prettier.config.js.

Prerequisites 

• Node.js v22.20.0 (see Build/resources/.nvmrc)
• Yarn package manager

Install dependencies:

cd Build/resources
yarn install

Commands 

cd Build/resources
yarn build

cd Build/resources
yarn start

cd Build/resources
yarn start:hot

Tech stack 

• Webpack 5 via @wordpress/scripts
• React with @r2wc/react-to-web-component for wrapping React components as custom elements
• Babel for JavaScript transpilation
• SCSS / PostCSS for stylesheets
• Yoast packages: yoastseo, @yoast/analysis-report, @yoast/components, @yoast/search-metadata-previews, @yoast/social-metadata-previews, and more

JavaScript entries 

Configured in Build/resources/webpack.config.js:

SCSS entries 

Webpack configuration 

The build uses a base configuration in Build/resources/webpack.config.base.js that extends @wordpress/scripts/config/webpack.config with:

• Babel loader for all .js files
• RemoveEmptyScriptsPlugin to clean up empty JS files generated from SCSS-only entries
• Custom DefinePlugin for process.env.NODE_DEBUG and SCRIPT_DEBUG
• The DependencyExtractionWebpackPlugin from @wordpress/scripts is removed since dependencies are bundled rather than externalized

How to import 

The web components are bundled in a single file that can be imported via the TYPO3 JavaScript module system. The module mapping is configured in Configuration/JavaScriptModules.php:

return [
    'dependencies' => ['core', 'backend', 'frontend_request'],
    'imports' => [
        '@yoast/yoast-seo-for-typo3/' => 'EXT:yoast_seo/Resources/Public/JavaScript/',
    ],
];

To load all web components, import the bundle in your JavaScript module:

import "@yoast/yoast-seo-for-typo3/dist/webcomponents.js"

After importing, all <yoast-*> custom elements are available for use in HTML.

Attribute naming convention 

The React components use camelCase property names, which are automatically converted to kebab-case HTML attributes by @r2wc/react-to-web-component. For example:

• faviconSrc becomes favicon-src
• wordsToHighlight becomes words-to-highlight
• readingTime becomes reading-time
• isLarge becomes is-large

Quick reference 

Component reference 

<yoast-loading-spinner></yoast-loading-spinner>

<yoast-title-progress-bar title="My page title"></yoast-title-progress-bar>

<yoast-description-progress-bar
    description="This is my meta description"
    date="Jan 1, 2025">
</yoast-description-progress-bar>

<yoast-snippet-preview
    title="My Page Title"
    url="https://example.com/my-page"
    description="A description of my page for search engines."
    favicon-src="/favicon.ico"
    locale="en_US"
    words-to-highlight='["SEO", "TYPO3"]'
    site-name="Example">
</yoast-snippet-preview>

<yoast-status-icon
    analysis-done
    result-type="seo"
    score="75">
</yoast-status-icon>

<yoast-analysis-result
    analysis='{"problemsResults":[],"improvementsResults":[],"goodResults":[],"considerationsResults":[],"errorsResults":[]}'>
</yoast-analysis-result>

<yoast-insights keywords='[{"name":"TYPO3","count":5},{"name":"SEO","count":3}]'></yoast-insights>

<yoast-flesch-reading-score score="65" difficulty="3"></yoast-flesch-reading-score>

<yoast-reading-time reading-time="5"></yoast-reading-time>

<yoast-word-count count="350" unit="words"></yoast-word-count>

<yoast-linking-suggestions
    links='[{"title":"Related page","url":"/related-page"}]'>
</yoast-linking-suggestions>

<yoast-facebook-preview
    site-base="https://example.com"
    title="My Page Title"
    description="A description for Facebook sharing."
    image-url="https://example.com/og-image.jpg">
</yoast-facebook-preview>

<yoast-twitter-preview
    site-base="https://example.com"
    title="My Page Title"
    description="A description for X sharing."
    image-url="https://example.com/twitter-image.jpg"
    is-large>
</yoast-twitter-preview>