diff --git a/docs/.drafts/seo/README.md b/docs/.drafts/seo/README.md deleted file mode 100644 index 95f406ce..00000000 --- a/docs/.drafts/seo/README.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -date: 2023-02-19 -description: Sprout SEO provides you an intuitive, seamless, and flexible way to manage your SEO strategy within Craft CMS. Content authors will enjoy a clear visual relationship between content and metadata where they can focus on content and maximize visibility. ---- - -# About Sprout SEO - -> Metadata is content too. - -Sprout SEO provides you an intuitive, seamless, and flexible way to manage your SEO strategy within Craft CMS. Content authors will enjoy a clear visual relationship between content and metadata where they can focus on content and maximize visibility. - -Sprout SEO helps manage several types of metadata: - -- Search -- Social Sharing -- Structured Data -- Sitemaps (See the [Sprout Sitemaps](./../sitemaps/README.md) docs for more info) -- Redirects (See the [Sprout Redirects](./../redirects/README.md) docs for more info) - -Refine your Metadata across three different levels of priority: - -- Global Metadata -- Element Metadata -- Template Metadata - -Often, the first time one of your visitors sees your content it is in search results or from a shared link. Make sure you're treating your metadata like a first class citizen alongside your content. - -Edit your content confidently. Throughout your content management experience, Sprout SEO will indicate which fields power the metadata on your site and provide some additional information about the scope and priority of how that field will affect your metadata. - -## Global Metadata - -[Global Metadata](./global-metadata.md) is managed from the Globals tab and filled out once when you setup Sprout SEO. Globals ensure you have metadata in place for your website identity and prepare Structured Data for your brand. Globals will help you communicate to the search engines information about your brand identity, how to get in touch, and general details so you always have something relevant about your business in search results and social sharing. - -![Global Metadata](./assets/images/seo/sproutseo-global-metadata.png) - -## Element Metadata - -**Element Metadata** is managed with the powerful [Metadata Field](./element-metadata-field.md). The Metadata field allows you to configure how your metadata is handled for every entry. If you want to have a tight integration with your existing content fields, you can reuse existing fields and the Metadata field will blend right into your existing content. If you want detailed control, you can enable overrides for each type of metadata and manage it all manually. - -![Element Metadata Field](./assets/images/seo/sprout-seo-fieldtype.png) - -## 100% control - -Sprout SEO is powered by a single tag to your templates. Place the optimize tag within the `` tag of your HTML page and you're up and running: - -``` twig -{% sproutseo 'optimize' %} -``` - -While the simple setup above should handle most use cases, Sprout SEO is also extremely customizable and gives you fine-grained control over all of your metadata. Sprout SEO also supports: - -- An API to add support for additional types of [URL-enabled Elements](../sitemaps/custom-url-enabled-sections.md) -- An API to add support for additional types of [Structured Data schemas](./custom-schema.md) -- Overriding metadata in your templates via [Template Overrides](./template-overrides.md) -- Overriding the default metadata templates using a [Custom Metadata Variable](./custom-metadata-variable.md) - -## Metadata Spreadsheet - -If you want to have a detailed understanding of all of the types of metadata supported by Sprout SEO and how the fields relate to those different types of metadata an their priorities, we have prepared a spreadsheet with all the details: - -- [Sprout SEO - Metadata Levels & Priorities](https://docs.google.com/spreadsheets/d/1OWvJVPkxdiqiemT2AMX76yPacLfi3aBuyRhgRy4_NIU/edit?usp=sharing) - -![Metadata Levels and Priorities Spreadsheet](./assets/images/seo/sprout-seo-metadata-spreadsheet.png) - -::: tip -We use the term **Metadata** to refer to all types of Metadata together. More specifically we may refer to **Meta Tags**, which are traditional metadata, and **Social Sharing**, which relies on a series of more specific Meta Tags around two specifications (Open Graph and Twitter) but applies to many other mediums as well from Pinterest to Slack chat, etc. Sprout SEO also let's you manage **Structured Data** (Knowledge Graph, Rich Cards) which supports many different **Schemas** and is output as JSON-LD in your templates. Finally, **Sitemap** metadata, allows you to define a list of URLs that search engines should know about on your site. -::: diff --git a/docs/.drafts/seo/custom-metadata-variable.md b/docs/.drafts/seo/custom-metadata-variable.md deleted file mode 100644 index cc440180..00000000 --- a/docs/.drafts/seo/custom-metadata-variable.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -date: 2023-02-19 -description: If you prefer to have full control over the metadata and how it is output on your pages, you can stop Sprout SEO from outputting metadata for you and just let it generate the metadata and make it available to your Twig template as a variable. ---- - -# Custom Metadata Variable - -Sprout SEO generates the metadata that is output to your pages with the `sproutseo` tag: - -``` twig -{% sproutseo 'optimize' %} -``` - -If you prefer to have full control over the metadata and how it is output on your pages, you can stop Sprout SEO from outputting metadata for you and just let it generate the metadata and make it available to your Twig template as a variable. - -This will give you control to change the output format, stop certain items from being output, and even output additional metadata in new ways to meet your needs. To give yourself control over your metadata variable, you'll need to update two Advanced settings: - -| Setting | Description | -|:---------------- |:----------- | -| **Automatically render metadata** | Disable this setting to stop Sprout SEO from outputting your metadata. | -| **Enable custom metadata variable** | Enable this setting and give your custom metadata variable a name. Sprout SEO will process your metadata and make it available to your template as this variable. | - -![Custom Metadata Variable](./assets/images/seo/sprout-seo-metadata-variable.png) - -To manage the metadata that Sprout SEO generates as a custom variable in your templates, you can do something like the following. Reference Sprout SEO's own template in `sproutseo/templates/_special/metadata.html` and be sure to continue to use the `{% sproutseo 'optimize' %}` tag _before_ you access your `metadata` variable in your templates (it's necessary to process your metadata and make the variable available): - -``` twig -{% sproutseo 'optimize' %} - -{%- set globals = metadata.globals -%} -{%- set meta = metadata.meta -%} -{%- set schema = metadata.schema %} - -{% for name, value in meta.search %} -{% switch name %} -{% case "title" %} - {{ value }} -{% case "author" %} - -{% case "publisher" %} - -{% default %} - -{% endswitch %} -{% endfor %} -{% for name, value in meta.robots %} -{% switch name %} -{% case "canonical" %} - -{% default %} - -{% endswitch %} -{% endfor %} -{% for name, value in meta.geo %} - -{% endfor %} -{% for name, value in meta.openGraph %} - -{% endfor %} -{% for name, value in meta.twitterCard %} - -{% endfor %} -{% for property in globals.ownership %} - -{% endfor %} - -{%- for item in schema -%} - {% if item %} - {{ item.getSchema() }} - {% endif %} -{%- endfor %} -``` diff --git a/docs/.drafts/seo/custom-schema.md b/docs/.drafts/seo/custom-schema.md deleted file mode 100644 index bd97f9af..00000000 --- a/docs/.drafts/seo/custom-schema.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -date: 2023-02-19 -description: Sprout SEO allows you to map your content in Craft CMS to the be output as Structured Data. ---- - -# Schema - -Sprout SEO allows you to map your content in Craft CMS to the be output as Structured Data. The mapping between your content and the Structured Data that gets output is called a schema. Sprout SEO supports two types of mappings: - -- **Default Schema Mappings** - a small, predictable subset of Schema Types and Properties that we can support out of the box. This will get you up and running and output more Structured Data for your content than the average website. -- **Custom Schema Mappings** - If you have more specialized content, Sprout SEO provides an extensive Schema API where you can map your content and custom fields and support more advanced schema mappings for your online and SEO strategies. - -## Custom Schema - -You can create your own Custom Schema by: - -1. Extending `Schema` with your Custom Schema -2. Register your Custom Schema using the registerSproutSeoSchemas() hook - -Sprout SEO uses its own Schema API. See over 15 Schema integration examples in Sprout SEO (sproutseo/integrations/sproutseo/schema). - -Download the [Example Custom Schema Plugin](https://s3.amazonaws.com/sprout.barrelstrengthdesign.com-assets/content/docs/examplecustomschema.zip) for an example of how to build a Custom Schema Integration as a separate plugin. The _Example Custom Schema Plugin_ includes lots of comments and some discussion of the available helper methods and other techniques to use while building your Custom Schema. - -Once you have created a Custom Schema, you should see it as an option in the Main Entity dropdown for your Sections and Element Metadata fields. It will only be processed and output as metadata on pages where you have it selected in your Main Entity settings. - -## Validation - -Structured Data schema are primarily defined on [schema.org](https://schema.org) but the vocabulary you see on schema.org is often not exactly the same as the feedback you get from Google's [Structured Data Testing Tool](https://search.google.com/structured-data/testing-tool). diff --git a/docs/.drafts/seo/faq.md b/docs/.drafts/seo/faq.md deleted file mode 100644 index 9fcae9ed..00000000 --- a/docs/.drafts/seo/faq.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -date: 2023-02-19 -description: Frequently asked questions about Sprout SEO. ---- - -# FAQ - -Frequently asked questions about Sprout SEO. - -## My page is outputting the wrong metadata? - -This is usually due to an incorrect setting or configuration somewhere. Check your settings and make sure you've assigned the right Element Metadata field to your Field Layout. Make sure your Custom Sections are enabled. - -A tricker one to troubleshoot is when matched variable names may take priority over one another in your template. Make sure you don't override the primary variable (`entry`, `category`, `product`, etc.) that Craft or a Custom Element Type makes available to the page, or any other URL-enabled pages: - -For example, a line that defines a `category` variable: - -``` twig -{% set category = product.category.last() %} -``` - -May override the expected `category` variable that Craft makes available to a Category page with URLs and also may override the `entry` or `product` variables on an Entry or Product Page with URLs. - -Avoid using the generic variable names that Craft depends on when possible and use more specific variable names such as `productCategory` to avoid unexpected behavior. diff --git a/docs/.drafts/seo/installing-and-updating-craft-3.md b/docs/.drafts/seo/installing-and-updating-craft-3.md deleted file mode 100644 index 1498fe5a..00000000 --- a/docs/.drafts/seo/installing-and-updating-craft-3.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -date: 2023-02-19 -description: Sprout SEO installation and update instructions for Craft 3. ---- - -# Craft 3 - -Sprout SEO installation and update instructions for Craft 3. - -## Requirements - -* Craft CMS 3.0.0 or a more recent version of Craft - -## Installation via Plugin Store - -1. Find the plugin in the Plugin Store in your Craft Control Panel -2. Go to _Settings → Plugins_ and select “Install” - -## Installation via Composer - -1. Open your terminal and go to your Craft project:
`cd /path/to/project` -2. Then tell Composer to load the plugin:
`composer require barrelstrength/sprout-seo` -3. In the Control Panel, go to _Settings → Plugins_ and select “Install” - -## Upgrading to Sprout SEO 4 - -Upgrading to Sprout SEO 4 requires upgrading to Craft 3. - -::: warning BEFORE YOU UPDATE -Make sure you have updated to the latest version of Sprout SEO 3.x before updating to Sprout SEO 4.x for Craft 3. The update from Sprout SEO 2 to 3 on Craft 2 was a larger update than the update from Sprout SEO 3 to 4 when migrating from Craft 2 to Craft 3. See the [Sprout SEO 3 upgrade documentation](./installing-and-updating-craft-2.md#updating-to-sprout-seo-3) for more details. -::: - -### Breaking changes - -#### Sections - -Sprout SEO 4 removes Section Metadata as it was largely not necessary and can be easily created within an existing site architecture using Singles, Channels, and the provided Metadata field. Any Section Metadata will need to be manually moved to an appropriate section and Element Metadata field. - -## Upgrading to Sprout SEO 4.4 - -Sprout SEO 4.4 updates how metadata is normalized and processed. For most users, these changes will not be noticed as metadata is generated and output in the same way. For users with custom implementations, please read below. - -### Breaking changes - -#### Metadata Model - -Retrieving metadata from the Metadata model is no longer done directly on the model. Metadata is now stored in Meta Type classes on the Metadata Model's `$metaTypes` attribute. Values on the model represent the raw data necessary to calculate the final values. The raw data can be retrieved by calling the `getRawData()` method. The calculated values can be retrieved by calling the `getMetaTagData()` method. - -``` php -$metadata = new barrelstrength\sproutseo\models\Metadata(); - -// Get all the static values stored that will be used to calculate the final metadata -$metadata->getRawData() - -// Get a multi-dimensional array metadata by Meta Type with key value arrays of all calculated metadata -$metadata->getMetaTagData() -``` - -Previously you could access meta attributes directly on the model. Using the updated Metadata model you will need to retrieve the calculated value by getting the metadata by type and calling the getter for the value you want to retrieve. See all Meta Types in the `sprout-seo/src/meta` folder of the plugin. - -``` php -# OLD -$prioritizedMetadataModel->title - -# NEW -$searchMetaType = $prioritizedMetadataModel->getMetaTypes('search'); -$searchMetaType->getTitle(); -``` - -#### Custom Schema - -Several values in Custom Schema are often determined by grabbing those metadata values from the Globals or Metadata models. As the Globals and Metadata models have changed, you will want to revisit any Custom Schema and ensure your data is being retrieved and processed properly. - -Optimized metadata values should now be retrieved using their getters: - -```php -$metadata = $this->prioritizedMetadataModel; - -# OLD -$title = $metadata->optimizedTitle; -$description = $metadata->optimizedDescription; -$image = $metadata->optimizedImage; -$keywords = $metadata->optimizedKeywords; - -# NEW -$title = $metadata->getOptimizedTitle(); -$description = $metadata->getOptimizedDescription(); -$image = $metadata->getOptimizedImage(); -$keywords = $metadata->getOptimizedKeywords(); -``` - -Previously image IDs were stored as arrays. They are now stored as the image ID as a string. - -``` php -$schema = $this->globals['identity']; - -# OLD -$imageId = $schema['image'][0] ?? null; - -# NEW -$imageId = $schema['image'] ?? null; -``` - -#### Globals meta column - -The `sproutseo_globals.meta` column has been removed and Global Metadata is now calculated at the time it is needed. If you referenced the Globals::$meta column in any custom implementations, you can now just call the getter for the metadata you want from the final Metadata model. - -## Upgrading to SEO 5.0.0 - UNRELEASED - -Sprout SEO 5 is a major release the includes an update to the underlying architecture. The Sprout SEO user experience will remain familiar but several conventions have changed. Most notably, the core codebase for `barrelstrength/sprout-seo` has been moved to the `barrelstrength/sprout-base` package so any custom code, translations, or direct links to the Sprout SEO Control Panel will need to be updated to target the new naming conventions. Plugin-specific Control Panel settings have also moved to the Craft settings area. - -| Feature | Old Name | New Name | -|:------- |:------ |:------ | -| CP URL | `admin/sprout-seo` | `admin/sprout/seo` | -| Template Variables | `craft.sproutSeo` | `sprout.seo` | -| Translation Category | `sprout-seo` | `sprout` | -| Controller Namespace | `barrelstrength/sproutseo/controllers` | `barrelstrength/sproutbase/app/seo/controllers` | -| Service Namespace | `barrelstrength/sproutseo/services` | `barrelstrength/sproutbase/app/seo/services` | -| Optimize Service | `SproutSeo::$app->optimize` | `SproutBase::$app->optimizeMetadata` | -| Optimize Service | `SproutSeo::$app->schema` | `SproutBase::$app->schemaMetadata` | diff --git a/docs/.drafts/seo/plugin-settings.md b/docs/.drafts/seo/plugin-settings.md deleted file mode 100644 index 1fc2526c..00000000 --- a/docs/.drafts/seo/plugin-settings.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -date: 2023-02-19 -description: Settings can be managed in the Control Panel or via a config file in config/sprout-seo.php ---- - -# Settings - -Settings can be managed in the Control Panel _Sprout SEO → Settings_ or via a config file in `config/sprout-seo.php`. As Redirect and Sitemap functionality are managed in separate modules, for file-based config overrides you'll want to use the config overrides for each respective module: `config/sprout-redirects.php` and `config/sprout-sitemaps.php`. See below for links to the documentation of each module. - -## Metadata - -``` php - 'Sprout SEO', - - // The maximum number of characters to allow for Meta Description fields - 'maxMetaDescriptionLength' => 160, - - // Sprout SEO prepares and outputs all of your metadata in your template - 'enableRenderMetadata' => true, - - // Make a global `metadata` variable available to all of your templates - 'useMetadataVariable' => false, - - // The name of the metadata variable available to your templates - // 'metadataVariable' => 'metadata' - - // Display field handle next to the field name in your Element Metadata - // field settings - 'displayFieldHandles' => false -]; -``` - -## Redirects - -- See [Sprout Redirects](../redirects/plugin-settings.md) for documentation of the Redirects settings - -## Sent Email - -- See [Sprout Sitemaps](../sitemaps/plugin-settings.md) for documentation of the Sitemap settings diff --git a/docs/.drafts/seo/template-overrides.md b/docs/.drafts/seo/template-overrides.md deleted file mode 100644 index 5ff69da4..00000000 --- a/docs/.drafts/seo/template-overrides.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -date: 2023-02-19 -description: Template Overrides allow you to modify your metadata in your Craft templates. ---- - -# Template Overrides - -Template Overrides allow you to modify your metadata in your Craft templates. While this can help with some scenarios, it is not always ideal as it makes it harder to give content authors control over all metadata in the Control Panel and increases the complexity of the codebase that needs to be managed over time. - -::: warning PROCEED WITH CAUTION -Template Overrides should be considered a last resort. If you feel you have no other options and need to use them, reach out and [let us know](mailto:sprout@barrelstrengthdesign.com). We'd love to understand your use case so we can improve Sprout SEO and make it less likely you need to use Template Overrides in the future. -::: - -## Templating - -Metadata defined in templates gets the highest priority when metadata is processed. - -The `meta` variable allows you to override metadata within templates. The `meta` variable must use the `do` tag syntax and must be run _before_ the `{% sproutseo 'optimize' %}` tag in your templates. - -### A Simple Page - -#### page.twig - -``` twig -{% do sprout.seo.meta({ - title: entry.title, -}) %} - -{% sproutseo 'optimize' %} -``` - -### Extending a Layout - -#### _layout.twig - -``` twig -{% sproutseo 'optimize' %} -``` - -#### section/_entry.twig (extends your layout) - -Below is an example of all of the values you can override. - -``` twig -{% do sprout.seo.meta({ - title: entry.title, - description: entry.body|striptags|slice(0, 150), - canonical: '', - robots: 'noindex,nofollow', - region: '', - placename: '', - latitude: '', - longitude: '', - ogTitle: '', - ogType: '', - ogUrl: '', - ogImage: '', - ogImageWidth: '', - ogImageHeight: '', - ogImageType: '', - ogSiteName: '', - ogAuthor: '', - ogPublisher: '', - ogDescription: '', - ogAudio: '', - ogVideo: '', - ogLocale: '', - twitterCard: '', - twitterSite: '', - twitterCreator: '', - twitterTitle: '', - twitterDescription: '', - twitterUrl: '', - twitterImage: '', - twitterPlayer: '', - twitterPlayerStream: '', - twitterPlayerStreamContentType: '', - twitterPlayerWidth: '', - twitterPlayerHeight: '', -}) %} -``` diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 49672f15..b694cfcf 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -93,6 +93,7 @@ export default defineConfig({ text: 'SEO Metadata', collapsed: false, items: [ + {text: 'Meta Tags & Schema', link: '/meta'}, {text: 'Redirects', link: '/redirects'}, {text: 'Sitemaps', link: '/sitemaps'}, {text: 'FAQ & Examples', link: '/examples-seo/faq'}, @@ -141,6 +142,7 @@ export default defineConfig({ items: [ {text: 'Data Studio', link: '/update-guides/data-studio'}, {text: 'Email', link: '/update-guides/email'}, + {text: 'SEO', link: '/update-guides/seo'}, {text: 'Redirects', link: '/update-guides/redirects'}, {text: 'Sitemaps', link: '/update-guides/sitemaps'}, ] @@ -195,15 +197,26 @@ export default defineConfig({ '/examples-seo/': [ { items: [ - {text: '← Back to SEO', link: '/redirects'}, + {text: '← Back to SEO', link: '/meta'}, ] }, { - text: 'Examples', + text: 'Metadata', items: [ {text: 'Troubleshooting FAQ', link: '/examples-seo/faq'}, + {text: 'Global Metadata in Templates', link: '/examples-seo/global-metadata-in-templates'}, + {text: 'Element Metadata Field', link: '/examples-seo/element-metadata-field'}, + {text: 'Template Metadata Overrides', link: '/examples-seo/template-metadata-overrides'}, + {text: 'Canonical URLs', link: '/examples-seo/canonical-urls'}, + {text: 'Block Search Robots', link: '/examples-seo/block-robots-on-dev-site'}, + {text: 'Elements Without URLs', link: '/examples-seo/elements-without-urls'}, + ] + }, + { + text: 'Redirects', + items: [ {text: 'Craft Globals', link: '/examples-seo/query-strings-in-redirects'}, - {text: 'Welcome Notification', link: '/examples-seo/redirect-workflows'}, + {text: 'Redirect Workflows', link: '/examples-seo/redirect-workflows'}, ] } ], diff --git a/docs/.drafts/seo/block-robots-on-dev-site.md b/docs/examples-seo/block-robots-on-dev-site.md similarity index 97% rename from docs/.drafts/seo/block-robots-on-dev-site.md rename to docs/examples-seo/block-robots-on-dev-site.md index 95b382db..7dab5377 100644 --- a/docs/.drafts/seo/block-robots-on-dev-site.md +++ b/docs/examples-seo/block-robots-on-dev-site.md @@ -17,7 +17,7 @@ In the example below, the conditional statement assumes we have created an `env` ``` twig {% if craft.config.env != 'live' %} - {% do sprout.seo.meta({ + {% do sprout.meta.update({ robots: { 'noindex': 1, 'nofollow': 1 } }) %} {% endif %} diff --git a/docs/.drafts/seo/canonical-urls.md b/docs/examples-seo/canonical-urls.md similarity index 96% rename from docs/.drafts/seo/canonical-urls.md rename to docs/examples-seo/canonical-urls.md index 36e414ef..e4a557d8 100644 --- a/docs/.drafts/seo/canonical-urls.md +++ b/docs/examples-seo/canonical-urls.md @@ -28,9 +28,7 @@ Overriding Canonical URLs in your templates breaks the relationship with XML Sit To override the `canonical` meta value on any given page in your templates, use the `sprout.seo.meta` tag and set the `canonical` attribute to the appropriate URL: ``` twig -{% do sprout.seo.meta({ +{% do sprout.meta.update({ canonical: customUrl, }) %} - -{% sproutseo 'optimize' %} ``` diff --git a/docs/.drafts/seo/element-metadata-field.md b/docs/examples-seo/element-metadata-field.md similarity index 83% rename from docs/.drafts/seo/element-metadata-field.md rename to docs/examples-seo/element-metadata-field.md index 6b904ade..09cd453e 100644 --- a/docs/.drafts/seo/element-metadata-field.md +++ b/docs/examples-seo/element-metadata-field.md @@ -1,6 +1,6 @@ --- date: 2023-02-19 -description: The Metadata field gives you fine-grained control over how Entry-specific metadata is recognized and managed for your content. +description: The Metadata Field can be used on Elements like Users and Tags, that do not support URLs by default. --- # Metadata Field @@ -29,17 +29,9 @@ The default Metadata fields include: The easiest way to manage your metadata is to map your Metadata fields to existing fields in your field layout. The Meta Title and Meta Description fields will be used for Search and Social Sharing metadata fields. The Meta Image field will be used for Social Sharing. -### Display Editable Field - -Select the **Display Editable Field** option if you want Sprout SEO to output a field in your Field Layout to manage a specific type of metadata metadata. - -::: warning -Choosing to Display Editable Fields will increase the amount of time and effort necessary to post your content and manage your metadata. This level of control may not be necessary and will require a higher ongoing budget to manage well. -::: - ### Add Custom Format -When the **Add Custom Format** option is selected, you can reference any fields available to your saved Element using Craft Object Syntax. For example, you could reference the Title field in your custom format as `{title}` or `{{ object.title }}` and a custom field as `{customFieldHandle}` or `{{ object.customFieldHandle }}`: +When the **Add Custom Format** option is selected, you can reference any fields available to your saved Element using Craft Object Syntax. For example, you could reference the Title field in your custom format as `{title}` or `{{ object.title }}` and a custom field as `{customFieldHandle}` or `{{ object.customFieldHandle }}`: ``` twig {title} - {region} - {year} @@ -78,4 +70,3 @@ When you add a Metadata field to an existing URL-Enabled Section's Field Layout, #### What happens to my existing metadata if I change my metadata mapping in my Metadata Field settings? When you update an existing Metadata field's settings, Sprout SEO will trigger a task to resave all Elements in any URL-Enabled Section that use your Metadata in its Field Layout. When each Element is saved, an updated version of your metadata will also be saved. - diff --git a/docs/.drafts/seo/elements-without-urls.md b/docs/examples-seo/elements-without-urls.md similarity index 92% rename from docs/.drafts/seo/elements-without-urls.md rename to docs/examples-seo/elements-without-urls.md index 38740010..79406f90 100644 --- a/docs/.drafts/seo/elements-without-urls.md +++ b/docs/examples-seo/elements-without-urls.md @@ -18,12 +18,9 @@ The [Metadata Field](./element-metadata-field.md) can be used on Elements like U {% set user = craft.users.id(1).one() %} {# Set the `id` variable to the Element ID that has your Metadata field #} -{% do sprout.seo.meta({ +{% do sprout.meta.update({ id: user.id }) %} - -{# Prepare your metadata #} -{% sproutseo 'optimize' %} ``` ## Custom Elements diff --git a/docs/examples-seo/faq.md b/docs/examples-seo/faq.md index 409ceee8..bfa60e5a 100644 --- a/docs/examples-seo/faq.md +++ b/docs/examples-seo/faq.md @@ -5,64 +5,19 @@ description: Sending an email can touch several different services so it can be # Troubleshooting FAQ -Sending an email can touch several different services so it can be tricky to diagnose just where something is going wrong. To get more familiar with the topic, see Craft's article [Troubleshooting Email Errors](https://craftcms.com/guides/troubleshooting-email-errors) or hear a discussion of several common issues in this Straight Up Craft hangout [Troubleshooting Email Errors Hangout](https://straightupcraft.com/events/troubleshooting-email-errors). +## My page is outputting the wrong metadata? -To diagnose an email issue, consider each step in the email process. Simplify your tests to try to rule out other issues and confirm each step is working as expected until you can confirm what is going wrong. Email configuration for a custom Craft CMS website can include: +This is usually due to an incorrect setting or configuration somewhere. Check your settings and make sure you've assigned the right Element Metadata field to your Field Layout. Make sure your Custom Sections are enabled. -- Server configuration -- Email Service Provider -- DNS settings -- Craft CMS -- Sprout Email -- Email Content -- Email Template -- Recipient Firewall -- Recipient Email Client +A tricker one to troubleshoot is when matched variable names may take priority over one another in your template. Make sure you don't override the primary variable (`entry`, `category`, `product`, etc.) that Craft or a Custom Element Type makes available to the page, or any other URL-enabled pages: -_Below is not meant to be a comprehensive list of steps to diagnose an email issue but a list of things you may want to consider, ask, or explore along the way._ +For example, a line that defines an `entry` variable: -## Server configuration +``` twig +{% set entry = entry.relationsField.one() %} +``` -Is the web server capable of sending emails? If so, which protocol does it use? PHP Mail and Sendmail are notoriously unreliable so you probably want to configure a third party service and proper SMTP server to send email to improve your changes at troubleshooting this level. +This will override the expected `entry` variable that Craft makes available to a Entry pages. -## Email Service Provider +Avoid using the generic variable names that Craft depends on when possible and use more specific variable names to avoid unexpected behavior. -Many Email Service Providers have a free tier that is sufficient for most small websites. Mailgun and Sparkpost are reasonable places to start and there are many others. If you are on AWS, SES is an easy option. - -Has your Email Service Provider been configured correctly? Often these services have tools that can confirm if your DNS appears to be configured correctly. - -## DNS settings - -Are the DNS settings for the domain the email is being sent configured correctly? This includes getting DKIM and SPF records setup that help your email get recognized as legitimate and avoid the spam bin. - -## Craft CMS - -Are the Email settings in Craft configured correctly? Double check you have the right info. Send a Test email to yourself from Craft's Email settings page to confirm that is working. - -## Craft Plugins - -Are there any additional settings that need to be set? This might include settings that integrate with a third-party API like Mailchimp or Sendgrid or the default From Address that will be used to send your emails. - -Make sure the From Address being used when sending your email matches the website domain that you are sending from. In some cases, if the From Address is different than the sending domain an email will be considered a higher risk and may trigger more spam filters. - -## Email Content - -Make sure your content is respectable. Salesy titles may trigger spam filters so make sure you are sending all caps or using trigger words in your titles: "FREE CASH $$$!!!". If your email includes images, consider how large they are. If your email is really long, some email clients might truncate it after a certain number of HTML characters if you are using tons of tables for layouts. - -If your content uses dynamic variables or logic they may cause the template to render incorrectly. Consider simplifying them to plain text, sending a test, and then adding them back one by one to diagnose which one may be causing the issue. - -## Email Template - -Are the email templates rendering correctly? If you are using Sprout Email's default setup, the default Email Template is quite simple and template issues would more likely be caused by the content discussed above. If you are using custom Email Templates, simplify the Email Templates to just include a simple word or two in plain text and send a test. If that works, add back your more complex template logic part by part until you diagnose what part of the template may be causing the issue. - -Take a look in your Craft logs files. They may reveal more about what is going on. - -## Recipient Firewall - -Sprout Email's Sent Email feature reports if an email was sent from Craft successfully. While a Sent Email Element can indicate success, that doesn't mean your email got delivered, it just means your email successfully got handed off by Craft to the next service. Email Service Providers often provide additional metrics on if an email was successfully routed. And, even though an Email Service Provider may report that your email has been sent successfully through its service, it does not mean your email made it to it's destination. - -Who is receiving the email? Does their organization have any business rules in their firewall or email configuration that may be filtering the email or labeling it as spam? Larger companies are more likely to have stricter rules in place in their firewall that may affect deliverability. Your behavior when testing emails can look suspicious but an IT department should be able to help you get whitelisted when needed. - -## Recipient Email Client - -What program is the recipient using to receive the email? Do they have any settings in place that may affect receiving the email? The last place to lose an email is in the recipients inbox itself. Some emails get filtered as spam, other people are just busy and archive an email before they realize it was your test email. If you've made it this far, follow up with your recipients and see what you can learn. Consider sending a test to a personal address instead of a business address to help diagnose where the issue may be arising. diff --git a/docs/.drafts/seo/global-metadata.md b/docs/examples-seo/global-metadata-in-templates.md similarity index 89% rename from docs/.drafts/seo/global-metadata.md rename to docs/examples-seo/global-metadata-in-templates.md index 40ad784d..a2f4f3d6 100644 --- a/docs/.drafts/seo/global-metadata.md +++ b/docs/examples-seo/global-metadata-in-templates.md @@ -1,13 +1,13 @@ --- date: 2023-02-19 -description: Global Metadata is managed from the Globals tab and filled out once when you setup Sprout SEO. Globals ensure you have metadata in place for your website identity and prepare Structured Data for your brand. +description: The Metadata Field can be used on Elements like Users and Tags, that do not support URLs by default. --- -# Global Metadata +# Global Metadata in Templates Global Metadata is managed from the Globals tab and filled out once when you setup Sprout SEO. Globals ensure you have metadata in place for your website identity and prepare Structured Data for your brand. Globals will help you communicate to the search engines information about your brand identity, how to get in touch, and general details so you always have something relevant about your business in search results and social sharing. -## Website Identity +### Website Identity ``` twig {% set globals = sprout.seo.getGlobalMetadata() %} @@ -45,7 +45,7 @@ Global Metadata is managed from the Globals tab and filled out once when you set {{ identity.address.address2 }} ``` -## Contacts +### Contacts ``` twig {% set globals = sprout.seo.getGlobalMetadata(currentSite) %} @@ -57,7 +57,7 @@ Global Metadata is managed from the Globals tab and filled out once when you set {% endfor %} ``` -### getContacts +#### getContacts You can display a list of the Contacts from your Global Sprout SEO settings on your website using the `getContacts` tag: @@ -71,7 +71,7 @@ You can display a list of the Contacts from your Global Sprout SEO settings on y ``` -## Social Profiles +### Social Profiles ``` twig {% set globals = sprout.seo.getGlobalMetadata(currentSite) %} @@ -83,7 +83,7 @@ You can display a list of the Contacts from your Global Sprout SEO settings on y {% endfor %} ``` -### getSocialProfilesTag +#### getSocialProfilesTag You can display a list of the Social Profiles in your Global Sprout SEO settings on your website using the `getSocialProfiles` tag: @@ -97,7 +97,7 @@ You can display a list of the Social Profiles in your Global Sprout SEO settings ``` -## Verify Ownership +### Verify Ownership ``` twig {% set globals = sprout.seo.getGlobalMetadata(currentSite) %} @@ -110,7 +110,7 @@ You can display a list of the Social Profiles in your Global Sprout SEO settings {% endfor %} ``` -## Customization +### Customization ``` twig {% set globals = sprout.seo.getGlobalMetadata(currentSite) %} @@ -125,7 +125,7 @@ You can display a list of the Social Profiles in your Global Sprout SEO settings {{ settings.appendTitleValue }} ``` -## Robots +### Robots ``` twig {% set globals = sprout.seo.getGlobalMetadata(currentSite) %} diff --git a/docs/examples-seo/template-metadata-overrides.md b/docs/examples-seo/template-metadata-overrides.md new file mode 100644 index 00000000..8ca41e5a --- /dev/null +++ b/docs/examples-seo/template-metadata-overrides.md @@ -0,0 +1,65 @@ +--- +date: 2023-02-19 +description: You have multiple options to customize the canonical URLs that appear in your metadata or in your XML sitemaps. +--- + +### Templating + +Metadata defined in templates gets the highest priority when metadata is processed. + +The `sprout.meta.update` variable allows you to override metadata within templates. The `sprout.meta.update` variable must use the `do` tag syntax. + +### A Simple Page + +#### page.twig + +``` twig +{% do sprout.meta.update({ + title: entry.title, +}) %} + +{% sproutseo 'optimize' %} +``` + +### section/_entry.twig (extends your layout) + +Below is an example of all of the values you can override. + +``` twig +{% do sprout.meta.update({ + title: entry.title, + description: entry.body|striptags|slice(0, 150), + canonical: '', + robots: 'noindex,nofollow', + region: '', + placename: '', + latitude: '', + longitude: '', + ogTitle: '', + ogType: '', + ogUrl: '', + ogImage: '', + ogImageWidth: '', + ogImageHeight: '', + ogImageType: '', + ogSiteName: '', + ogAuthor: '', + ogPublisher: '', + ogDescription: '', + ogAudio: '', + ogVideo: '', + ogLocale: '', + twitterCard: '', + twitterSite: '', + twitterCreator: '', + twitterTitle: '', + twitterDescription: '', + twitterUrl: '', + twitterImage: '', + twitterPlayer: '', + twitterPlayerStream: '', + twitterPlayerStreamContentType: '', + twitterPlayerWidth: '', + twitterPlayerHeight: '', +}) %} +``` diff --git a/docs/features.md b/docs/features.md index f0ccd97d..2283feb7 100644 --- a/docs/features.md +++ b/docs/features.md @@ -56,15 +56,11 @@ _Available in: Sprout Email, Sprout Sent Email._ [//]: # () -[//]: # (## Meta Module) +## Meta Module -[//]: # () - -[//]: # (_Available in: Sprout SEO._) - -[//]: # () +_Available in: Sprout SEO._ -[//]: # () + ## Redirects Module diff --git a/docs/meta.md b/docs/meta.md new file mode 100644 index 00000000..33b61c55 --- /dev/null +++ b/docs/meta.md @@ -0,0 +1,90 @@ +--- +date: 2024-03-16 +description: Manage meta tags and schema for multi-lingual and multi-regional sites. +--- + +# About Meta Tags & Schema + +> Metadata is content too + +Sprout provides an intuitive, seamless, and flexible way to manage your SEO strategy within Craft CMS. Content authors will enjoy a clear visual relationship between content and metadata where they can focus on content and maximize visibility. + +Throughout your content management experience, the Meta module will indicate which fields power the metadata on your site and provide some additional information about the scope and priority of how that field will affect your metadata. + +Meta Tags and Structured Data will be automatically rendered in your templates (no template updates are required). + +::: tip TECHNICAL METADATA +We use the term **Metadata** to refer to all types of Metadata together. More specifically we may refer to **Meta Tags**, which are traditional metadata, and **Social Sharing**, which relies on a series of more specific Meta Tags around two specifications (Open Graph and Twitter) but applies to many other mediums as well from Pinterest to Slack and more. The Meta module also let's you manage **Structured Data** (Knowledge Graph, Rich Cards) which supports many different **Schemas** and is output as JSON-LD in your templates. +::: + +## Meta Tags + +Often, the first time a visitor sees your content it is in search results or via the highlighted metadata when a link is shared in another application. Make sure you're treating your metadata like a first class citizen alongside your content. + +Manage Meta Tags including: + +- Search (Title, Description, Image, etc.) +- Social Sharing (Facebook, Twitter, etc.) +- Robots (noindex, nofollow, etc.) + +## Structured Data + +Map your content in Craft CMS to the be output as Structured Data. The mapping between your content and the Structured Data that gets output is called a Schema. There are two types of mappings: + +- **Default Schema Mappings** - a small, predictable subset of Schema Types and Properties that we can support out of the box. This will get you up and running and output more Structured Data for your content than the average website. +- **Custom Schema Mappings** - If you have more specialized content, the Meta module provides an extensive Schema API where you can map your content and custom fields and support more advanced schema mappings for your online and SEO strategies. + +## Optimized Metadata + +Refine your Metadata across three different levels of priority. + +### Global Metadata + +**Global Metadata** is managed from the SEO tab and filled out once when you setup the Meta module. Globals ensure you have metadata in place for your website identity and prepare Structured Data for your brand. Globals will help you communicate to the search engines information about your brand identity, how to get in touch, and general details so you always have something relevant about your business in search results and social sharing. + +![Global Metadata](./assets/images/seo/sproutseo-global-metadata.png) + +See the [Global Metadata in Templates](./examples-seo/global-metadata-in-templates.md) examples for more details. + +### Element Metadata + +**Element Metadata** is managed with the powerful [Metadata Field](./examples-seo/element-metadata-field.md). The Metadata field allows you to configure how your metadata is mapped for entry content. If you want to have a tight integration with your existing content fields, you can reuse existing fields and the Metadata field will blend right into your existing content. If you want detailed control, you can enable overrides for each type of metadata and manage it all manually. + +![Element Metadata Field](./assets/images/seo/sprout-seo-fieldtype.png) + +See the [Metadata Field](./examples-seo/element-metadata-field.md) examples for more details. + +### Template Metadata + +**Template Metadata** allows you to modify your metadata in your Craft templates. While this can help with some scenarios, it is not always ideal as it makes it harder to give content authors control over all metadata in the Control Panel and increases the complexity of the codebase that needs to be managed over time. + +::: warning PROCEED WITH CAUTION +Template Overrides should be considered a last resort. If you feel you have no other options and need to use them, reach out and [let us know](mailto:sprout@barrelstrengthdesign.com). We'd love to understand your use case so we can improve the Meta module and make it less likely you need to use Template Overrides in the future. +::: + +See the [Template Metadata](./examples-seo/template-metadata-overrides.md) examples for more details. + +## Developers + +### Custom Schema + +To add Custom Schema support for custom Structured Data mappings extend the `Schema` class and register your new class via `EVENT_REGISTER_SCHEMAS`. + +``` php +use BarrelStrength\Sprout\meta\schema\Schema; + +class MyCustomSchema extends Schema +{ + ... +} +``` + +See the Sprout codebase for examples. + +## Settings + +Read the [Config Settings](./configuration/sprout-config.md) documentation to explore and customize settings. + +## Updates + +See [update guides](/update-guides/seo.md) for the SEO and Framework modules. diff --git a/docs/public/editions/seo.json b/docs/public/editions/seo.json index 16bf66f4..868f0c25 100644 --- a/docs/public/editions/seo.json +++ b/docs/public/editions/seo.json @@ -15,7 +15,7 @@ "pro": true }, { - "name": "Verify Ownership", + "name": "Verify Ownership Metadata", "info": "", "lite": true, "pro": true @@ -50,26 +50,31 @@ "pro": true }, { - "name": "Unlimited Metadata Fields", - "info": "", + "name": "Unlimited Metadata Mappings", + "info": "Create unique metadata mappings in any field layout.", "lite": false, "pro": true }, { - "name": "Custom Metadata Patterns", - "info": "", + "name": "Custom Mapping Patterns", + "info": "Optimize your metadata by defining custom patterns that use data from more than one field.", "lite": false, "pro": true }, { - "name": "Custom Metadata Overrides", - "info": "", + "name": "Template Metadata", + "info": "Override metadata at any point during Twig template rendering.", "lite": false, "pro": true - }, + } + ] + }, + { + "category": "Developers", + "items": [ { - "name": "Template Metadata", - "info": "", + "name": "Custom Schema API", + "info": "Build the precise structured data mappings you need.", "lite": false, "pro": true } diff --git a/docs/update-guides/data-studio.md b/docs/update-guides/data-studio.md index 1b031f84..3219689c 100644 --- a/docs/update-guides/data-studio.md +++ b/docs/update-guides/data-studio.md @@ -3,7 +3,7 @@ date: 2023-09-25 description: Sprout Data Studio update guide. --- -# Data Studio +# Updating Data Studio ## v4.44.444 - February 20, 2023 diff --git a/docs/update-guides/email.md b/docs/update-guides/email.md index c06aab07..1069c14b 100644 --- a/docs/update-guides/email.md +++ b/docs/update-guides/email.md @@ -3,9 +3,9 @@ date: 2023-09-25 description: Sprout Email update guide. --- -# Email +# Updating Email -## 4.44.444 - September 5, 2023 +## v4.44.444 - September 5, 2023 The Transactional Email Module manages Sprout's core notification email functionality and in this major release adds significant features such as Audiences, Email Types, and the Notification Event Condition Builder. diff --git a/docs/update-guides/index.md b/docs/update-guides/index.md index c2ad8efb..d1af3b42 100644 --- a/docs/update-guides/index.md +++ b/docs/update-guides/index.md @@ -22,4 +22,5 @@ The update guides are primarily for notable changes. Not all plugin versions wil - [Sprout Data Studio](./data-studio.md) - [Sprout Email](./email.md) - [Sprout Redirects](./redirects.md) +- [Sprout Seo](./seo.md) - [Sprout Sitemaps](./sitemaps.md) diff --git a/docs/update-guides/redirects.md b/docs/update-guides/redirects.md index d3163b76..ac69ada2 100644 --- a/docs/update-guides/redirects.md +++ b/docs/update-guides/redirects.md @@ -3,7 +3,7 @@ date: 2023-09-25 description: Sprout Redirects update guide. --- -# Redirects +# Updating Redirects ## v4.44.444 - February 20, 2023 diff --git a/docs/update-guides/seo.md b/docs/update-guides/seo.md new file mode 100644 index 00000000..c3891e59 --- /dev/null +++ b/docs/update-guides/seo.md @@ -0,0 +1,49 @@ +--- +date: 2024-03-18 +description: Sprout SEO update guide. +--- + +# Updating SEO + +## v4.44.444 - UNRELEASED + +This release adds Craft 4 support and simplifies the feature set around managing and rendering metadata. + +### Breaking Changes + +Review the following notes carefully as you will need to take at least one manual step after updating to ensure your templates load metadata correctly. + +---- + +#### Metadata is now rendered automatically + +In Craft 3, the `{% sproutseo 'optimize' %}` tag was necessary to render metadata. + +In Craft 4, metadata is rendered automatically. The `{% sproutseo 'optimize' %}` tag is no longer necessary and must be removed from your templates. Metadata will be rendered dynamically. + +---- + +#### Template tags have been updated + +In Craft 3, the `craft.sproutSeo` tag was used in templates (i.e. `craft.sproutSeo.meta`). + +In Craft 4, use the `sprout.meta` tag (i.e. `sprout.meta.update`). + +---- + +#### Editable Field Metadata Field setting has been removed + +In Craft 3, a developer could configure a Metadata field to use the Editable Field setting and Sprout would output Title, Description, and Image fields for content editors to use in their SEO workflow. + +In Craft 4, the Editable Field setting has been removed and any metadata using Editable Fields has migrated to use the Search Meta Details settings. The migration respects the priority of the existing metadata. If a Search Metadata field was null, the Editable Field value will be used. If the Search Metadata field was not null, the Search Metadata field value will be used. + +::: warning CUSTOM ELEMENTS +Editable Field migration handles Elements that store their content in the primary content table. If you are using an Element Metadata field on a custom or third-party element that stores it's data in a different content table, you will need to handle that migration on your own. +::: + +### Framework + +- See the general [upgrade guide][#400-framework] for Sprout Modules to 4.0 + +[#400-framework]: /update-guides/sprout.md + diff --git a/docs/update-guides/sitemaps.md b/docs/update-guides/sitemaps.md index aae213e8..97d61139 100644 --- a/docs/update-guides/sitemaps.md +++ b/docs/update-guides/sitemaps.md @@ -3,7 +3,7 @@ date: 2023-09-25 description: Sprout Sitemaps update guide. --- -# Sitemaps +# Updating Sitemaps ## v4.44.444 - September 25, 2023