[Feature]: Issue 240 | SEO Descriptions

[TylerB24890]

What?

Closes #240

This PR introduces a new Experiment "Meta Descriptions" which provides AI generated meta description support.

Why?

Meta descriptions are an important aspect of a pages SEO, yet they are often overlooked or lacking in quality. See #240 for more detail.

How?

This Experiment introduces a new panel to the block editor PluginDocumentSettingPanel for managing the SEO meta description for the current post. The initial view provides a simple button to "Generate Meta Description". On click of the button, a modal window opens which shows the suggested meta descriptions returned from the AI and a TextAreaControl input allowing editors to manipulate the suggested descriptions prior to saving them to the post.

On select of a suggestion, the TextareaControl component is populated with the selected suggestion at which point the editor can update the text as needed.

From there, editors have a few options;

• Clicking "Apply" will save the content from the TextareaControl component to the appropriate meta key
  • If a supported SEO plugin is installed and active, the plugins meta key will be used. Otherwise a default _meta_description key is stored.
• Clicking "Copy to Clipboard" will copy the content from the TextareaControl to the users clipboard.
• Clicking "Cancel" will close the modal without applying any meta description changes.
• Clicking "Regenerate suggestions" will send the prompt to the AI again for a new set of suggestions.

Various filters are available for customizing the experiment;

• wpai_meta_description_prompt - Attach additional (or modify) context sent to the AI for the meta description
• wpai_meta_description_result_temperature - The temperature threshold for the model. Default is 0.7
• wpai_meta_description_seo_plugin - The supported SEO plugins in ['file' => 'path', 'meta_key' => 'key' ] format.
  • Default supported plugins: YoastSEO, RankMath, All in One SEO, SEOPress
  • This configuration is what determines the meta key the description is saved to.
• wpai_meta_description_meta_key - Override the meta key the description is saved to. This will take priority over any plugin configurations.
• wpai_meta_description - Override the output of the meta description. This filter only runs when an SEO plugin is not detected.

Use of AI Tools

• AI Assistance: Yes
• Tool(s): Claude Code (Opus 4.6)
• Used for:
  • Experiment scaffolding
  • Unit test boilerplates
  • Debugging support & code suggestions
  • Inline documentation and experiment documentation generation
  • Assistance with the system prompt generation

Testing Instructions

1. Visit the Experiments settings page in wp-admin and enable the Meta Descriptions Experiment.
2. Navigate to a post and confirm the Meta Description panel exists just below the "Move to Trash" button (should be the top panel above Categories)
3. Click the "Generate meta description" button. The modal window should open with the suggested descriptions available for selection.
4. Select a meta description and confirm the content is dropped into the Text Area for customization.
5. Customize the description and click the Apply button. The Meta Description panel in the sidebar should now show the description with an option to Edit or Regenerate.
6. Save the post and confirm the meta description remains after refresh.
7. Edit the meta description and confirm the content is saved as expected.
8. Regenerate the meta description and confirm the content is saved as expected.
9. Install Yoast SEO plugin
10. Repeat steps 1-9 and confirm the meta description is saved to the YoastSEO meta key instead of the default _meta_description key.
11. Repeat step 9-10 for each of the supported plugins.

Screenshots or screencast

Initial State:

Generated Descriptions:

Selected Description:

Saved Description:

[codecov]

Codecov Report

❌ Patch coverage is 77.48092% with 59 lines in your changes missing coverage. Please review.
✅ Project coverage is 64.84%. Comparing base (f83fa57) to head (e85f1f3).
⚠️ Report is 65 commits behind head on develop.

Files with missing lines	Patch %	Lines
...es/Abilities/Meta_Description/Meta_Description.php	80.41%	28 Missing ⚠️
.../Experiments/Meta_Description/Meta_Description.php	63.63%	28 Missing ⚠️
...des/Abilities/Meta_Description/SEO_Integration.php	95.00%	2 Missing ⚠️
.../Abilities/Meta_Description/system-instruction.php	50.00%	1 Missing ⚠️

Additional details and impacted files

@@              Coverage Diff              @@
##             develop     #318      +/-   ##
=============================================
+ Coverage      63.89%   64.84%   +0.94%     
- Complexity       680      740      +60     
=============================================
  Files             49       53       +4     
  Lines           3518     3780     +262     
=============================================
+ Hits            2248     2451     +203     
- Misses          1270     1329      +59     

Flag	Coverage Δ
unit	64.84% <77.48%> (+0.94%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[jeffpaul]

1. Update experiment title to Meta Description Generation, though I'm open to collapsing this into the Excerpt Generation experiment as they're so closely related (Excerpt and Meta Description Generation)

2. Update button text to Title Case from Sentence case

3. Update the loading text of the Regenerate suggestions button to Generating

4. Generating meta, clicking save on a draft post, exiting the editor, and then returning shows no meta still saved to the post. Same problem generating meta, publishing a post, exiting the editor, and then coming back into the post shows no meta saved. So something's off with saving that to the post, here's my setup: WordPress 7.0-beta5-62069 and AI Provider for Google Version 1.0.3.

I've not yet tested across the SEO plugins, will do that once the meta saving issue above is resolved as that seems like it may heavily impact the plugin compatibility/integration.

[TylerB24890]

@jeffpaul

Update experiment title to Meta Description Generation, though I'm open to collapsing this into the Excerpt Generation experiment as they're so closely related (Excerpt and Meta Description Generation)

I've updated the experiment title to "Meta Description Generation" -- let me know if we should roll this up into the Excerpt UI instead.

Update button text to Title Case from Sentence case

Done.

Update the loading text of the Regenerate suggestions button to Generating

Done.

Generating meta, clicking save on a draft post, exiting the editor, and then returning shows no meta still saved to the post. Same problem generating meta, publishing a post, exiting the editor, and then coming back into the post shows no meta saved. So something's off with saving that to the post, here's my setup: WordPress 7.0-beta5-62069 and AI Provider for Google Version 1.0.3.

This is because metadata isn't saved with Drafted posts by default. I had to define the revisions_enabled => true property when registering the _meta_description meta field. This has been updated to enable revisions for this meta key so it should save with Drafted posts going forward.

[TylerB24890]

@dkotter I've resolved all feedback and removed the candidate_count logic. I've also added is_supported_* logic as requested in #313

Instead of presenting a user with multiple suggested SEO descriptions, they are now shown one description inside a textarea for modification:

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: TylerB24890 <tyb@git.wordpress.org>
Co-authored-by: dkotter <dkotter@git.wordpress.org>
Co-authored-by: jeffpaul <jeffpaul@git.wordpress.org>
Co-authored-by: phil-sola <philsola@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[dkotter]

This all looks good to me, nice work here @TylerB24890! The only last comment/question I had, which I left in a threaded comment but pulling out here for easier tracking, is whether we want to actually render a meta description tag if no SEO plugin is installed?

Right now you can generate the meta description but if you aren't using an SEO plugin (which if we're honest is probably a small percentage of sites) this field is never used anywhere.

Curious for your thoughts here @jeffpaul

[TylerB24890]

This all looks good to me, nice work here @TylerB24890! The only last comment/question I had, which I left in a threaded comment but pulling out here for easier tracking, is whether we want to actually render a meta description tag if no SEO plugin is installed?

Right now you can generate the meta description but if you aren't using an SEO plugin (which if we're honest is probably a small percentage of sites) this field is never used anywhere.

Curious for your thoughts here @jeffpaul

That's a good flag. We don't really have a good way to determine if its already being rendered or not unless a known plugin is active (besides parsing the rendered page, which I wouldn't consider a good way)

If we decide to limit this to an SEO plugin being active would we hide the experiment activation all together or just the UI from the block editor?

[dkotter]

If we decide to limit this to an SEO plugin being active would we hide the experiment activation all together or just the UI from the block editor?

I wouldn't personally. I think this is still a good feature to have, even though I'd expect most SEO plugins today to have their own AI integrations. So I think it's good that we change where the data is stored depending on if an SEO plugin is active but I wouldn't disable everything if a plugin is active. Just wondering if we should output the meta tag if no SEO plugin is active but leave everything else as-is.

[jeffpaul]

Let's output the meta tag if no SEO plugin is detected, worst case there are dupe tags on that page?

[TylerB24890]

Let's output the meta tag if no SEO plugin is detected, worst case there are dupe tags on that page?

@jeffpaul @dkotter I've added some logic to hook into wp_head & output the meta description if the experiment is enabled and no SEO plugin is detected. Also added unit tests & updated experiment documentation accordingly.

[TylerB24890]

@dkotter It appears the inclusion of the is_supported_* check here is causing the E2E tests to fail. The is_supported_for_text_generation() check requires the AI provider to be fully "connected" at the registration level, which fails in the E2E test environment where the mock plugin only intercepts outgoing HTTP requests.

This is also happening in the recently merged Content Classification experiment E2E tests. I'm pretty positive this did work prior to me merging the most recent develop branch though, so I'm not really sure why they're failing now. Any thoughts on how we should approach it?

generate_text() returns a WP_Error when no provider is available as well -- should we remove the experiment is_supported_* check and fallback to the generate_text error message?