From 89c151ebd765f936d94f6034de35e2b718f5acf6 Mon Sep 17 00:00:00 2001
From: Austin Gilmour <gilmoursa@gmail.com>
Date: Fri, 15 May 2026 17:28:58 -0400
Subject: [PATCH] webp-uploads: Link to FAQ from Modern Image Formats settings
 section

Adds a description paragraph to the Modern Image Formats settings
section that links to the plugin FAQ on WordPress.org, so users can
understand why converted images may not appear after upload without
leaving the admin dashboard.

Fixes #2442
---
 plugins/webp-uploads/settings.php            | 21 +++++++++++++++++++-
 plugins/webp-uploads/tests/test-settings.php | 12 +++++++++++
 2 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/plugins/webp-uploads/settings.php b/plugins/webp-uploads/settings.php
index 78cccb2140..18c0d33ab4 100644
--- a/plugins/webp-uploads/settings.php
+++ b/plugins/webp-uploads/settings.php
@@ -70,6 +70,25 @@ function webp_uploads_register_media_settings_field(): void {
 }
 add_action( 'init', 'webp_uploads_register_media_settings_field' );
 
+/**
+ * Renders the description for the Modern Image Formats settings section.
+ *
+ * @since n.e.x.t
+ */
+function webp_uploads_modern_image_formats_section_callback(): void {
+	printf(
+		'<p class="description">%s</p>',
+		wp_kses(
+			sprintf(
+				/* translators: %s: URL to the plugin FAQ. */
+				__( 'If converted images are not appearing as expected after upload, refer to the <a href="%s">FAQ</a> for common reasons why.', 'webp-uploads' ),
+				'https://wordpress.org/plugins/webp-uploads/#faq'
+			),
+			array( 'a' => array( 'href' => array() ) )
+		)
+	);
+}
+
 /**
  * Adds media settings field for the 'perflab_generate_webp_and_jpeg' setting.
  *
@@ -79,7 +98,7 @@ function webp_uploads_add_media_settings_fields(): void {
 	add_settings_section(
 		'perflab_modern_image_format_settings',
 		_x( 'Modern Image Formats', 'settings page section name', 'webp-uploads' ),
-		'__return_empty_string',
+		'webp_uploads_modern_image_formats_section_callback',
 		'media',
 		array(
 			'before_section' => '<div id="modern-image-formats">',
diff --git a/plugins/webp-uploads/tests/test-settings.php b/plugins/webp-uploads/tests/test-settings.php
index 0d167b1d09..d6fca9f6cf 100644
--- a/plugins/webp-uploads/tests/test-settings.php
+++ b/plugins/webp-uploads/tests/test-settings.php
@@ -7,6 +7,18 @@
 
 class Test_WebP_Uploads_Settings extends WP_UnitTestCase {
 
+	/**
+	 * @covers ::webp_uploads_modern_image_formats_section_callback
+	 */
+	public function test_webp_uploads_modern_image_formats_section_callback(): void {
+		ob_start();
+		webp_uploads_modern_image_formats_section_callback();
+		$output = ob_get_clean();
+
+		$this->assertStringContainsString( 'https://wordpress.org/plugins/webp-uploads/#faq', $output );
+		$this->assertStringContainsString( '<p class="description">', $output );
+	}
+
 	/**
 	 * @covers ::webp_uploads_add_settings_action_link
 	 */