Related Posts: enqueue block stylesheet on the block render path

[jeherve]

Fixes JETPACK-1876

Proposed changes

The Related Posts block renders through its own block callback, but its frontend stylesheet was never enqueued by the block itself. The CSS (modules/related-posts/related-posts.css) is only enqueued as a side effect of the module's front-end asset gate, enabled_for_request() — which on classic themes only fires on single posts (is_single()). So a Related Posts block placed on a page (or any view the gate skips) rendered its jp-relatedposts-i2 markup with no matching CSS: an unstyled bullet list with full-size images and visible dt/dd labels.

This enqueues the stylesheet inside render_block(), right after we know the block will output markup, reusing the module's existing enqueue_assets( false, true ) helper (handle jetpack_related-posts, including RTL + AMP handling). The block is now styled everywhere it can be placed, independent of theme type or the page/post distinction.

• Enqueue the block's stylesheet on the block render path, whenever the block actually renders related posts.
• Add a regression test asserting the style is enqueued when the block renders without the module's gate having run.

Deliberately not changed: enabled_for_request() is left untouched. That gate governs the automatic the_content insertion of related posts and was intentionally scoped in #39784 to avoid auto-appending related posts to classic-theme pages (#39783). Widening it would re-introduce that bug. The fix is confined to the block render path — it only adds CSS to markup the user explicitly placed — so the auto-insertion behavior is unchanged. The enqueue is idempotent on single posts, where the module already enqueues the same handle.

Related product discussion/links

• Guards against regressing Related Posts showing up on pages on Classic Themes #39783 / Related Posts: only enable on all singular views in block themes #39784

Does this pull request change what data or activity we track or use?

No.

Testing instructions

Related Posts can render three ways (block, [jetpack-related-posts] shortcode, automatic the_content insertion) and behaves differently on classic vs. block themes, so please cover the matrix below. This fix only changes the block render path; the shortcode and automatic-insertion paths are intentionally unchanged.

Setup

• Start with a site connected to WordPress.com, with the Related Posts module active (Settings → Reading) and several published posts and pages that will match as related content.

1. The fix — classic theme, block on a page

• Activate a classic theme (e.g. Twenty Twenty-One).
• Edit a Page (not a post), add a Related Posts block, and publish.
• View the Page on the frontend.
  • Before this PR: related posts render as an unstyled vertical list — full-width images, visible "Date"/"Author" labels, no grid.
  • After this PR: related posts render with their normal grid styling, and a jetpack_related-posts stylesheet is present on the page.

2. Block inserted via a Site Editor template (block theme)

This is a different insertion path than "block inside post content", and it's the path #39784 was tested against.

• Switch to a block theme (e.g. Twenty Twenty-Five).
• Go to Appearance → Editor → Templates → Single Posts, add a Related Posts block at the bottom, and save.
• Go to Appearance → Editor → Templates → Pages, add a Related Posts block at the bottom, and save.
• View the frontend of both a post and a page → related posts should render styled in both.

3. AMP

The AMP path is the only other caller of the changed method.

• With the AMP plugin active (or ?amp on a supported setup), view a post that shows related posts.
• Confirm the related posts are styled (CSS is inlined for AMP) and the page still validates.

4. Regression checks (behavior should be unchanged)

• Classic theme + block on a single post: still styled, and there is exactly one jetpack_related-posts stylesheet on the page (no double-enqueue).
• Block theme + block in post and page content: still styled.
• Automatic insertion (Related Posts enabled in Settings → Reading, no block, classic theme, single post): related posts still appear at the bottom of the post, styled.
• Classic theme, pages without the block: still show no auto-inserted related posts (guards Related Posts showing up on pages on Classic Themes #39783).
• Shortcode [jetpack-related-posts] on a single post: still renders as before.

5. Nice-to-have

• RTL locale (e.g. Hebrew): the RTL stylesheet loads for the block.
• Page Optimize active (the plugin present on the reported site): the block's CSS still applies after style concatenation.
• Block on a page with no available related posts (fresh site): the block renders nothing and no stray jetpack_related-posts stylesheet is loaded.

Automated: jetpack docker phpunit jetpack -- --filter=Jetpack_RelatedPosts_Test → OK (5 tests, 8 assertions).

[github-actions]

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

• To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack), and enable the fix/related-posts-block-css-enqueue branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack fix/related-posts-block-css-enqueue

Interested in more tips and information?

• In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
• Read more about our development workflow here: PCYsg-eg0-p2
• Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

[github-actions]

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

• ✅ Include a description of your PR changes.
  
• ✅ Add a "[Status]" label (In Progress, Needs Review, ...).
  
• ✅ Add testing instructions.
  
• ✅ Specify whether this PR includes any changes to data or privacy.
  
• ✅ Add changelog entries to affected projects
  

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

---

Follow this PR Review Process:

1. Ensure all required checks appearing at the bottom of this PR are passing.
2. Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
3. You can use GitHub's Reviewers functionality to request a review.
4. When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

---

Jetpack plugin:

No scheduled milestone found for this plugin.

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

[jp-launch-control]

Code Coverage Summary

Cannot generate coverage summary while tests are failing. 🤐

Please fix the tests, or re-run the Code coverage job if it was something being flaky.

Full summary · PHP report · JS report