Plugin Compatibility Layer Update: Yoast SEO LLMs.txt

[jazzsequence]

Problem

Yoast SEO 25.3 introduced the LLMs.txt feature, which writes a physical llms.txt file to the WordPress webroot (get_home_path()) and refreshes it weekly via WP-Cron.

On Pantheon, the Test and Live environments have a read-only codebase, so Yoast cannot write or update this file in those environments. The feature silently fails on every weekly cron run.

This is documented in the Pantheon known issues page: https://docs.pantheon.io/wordpress-known-issues#yoast-llms-feature

Proposed Solution

Yoast SEO 25.4 introduced the wpseo_llmstxt_filesystem_path filter specifically to handle server environments with filesystem restrictions. It allows redirecting the write location to any writable path.

The compatibility layer should apply this filter to redirect writes to wp-content/uploads, which is part of Pantheon's writable filesystem across all environments.

Implementation

A new fix class:

// inc/compatibility/fixes/class-yoastseollmstxtfix.php

<?php
namespace Pantheon\Compatibility\Fixes;

class YoastSeoLlmsTxtFix {
    public static function apply() {
        AddFilterFix::apply( 'wpseo_llmstxt_filesystem_path', [ self::class, 'redirect_llmstxt_path' ] );
    }

    public static function remove() {
        AddFilterFix::remove( 'wpseo_llmstxt_filesystem_path', [ self::class, 'redirect_llmstxt_path' ] );
    }

    public static function redirect_llmstxt_path(): string {
        return WP_CONTENT_DIR . '/uploads';
    }
}

A new compatibility class:

// inc/compatibility/class-yoastseo.php

<?php
/**
 * Compatibility class for Yoast SEO LLMs.txt feature.
 *
 * @link https://docs.pantheon.io/wordpress-known-issues#yoast-llms-feature
 * @package Pantheon\Compatibility
 */

namespace Pantheon\Compatibility;

use Pantheon\Compatibility\Fixes\YoastSeoLlmsTxtFix;

class YoastSeo extends Base {
    protected $run_fix_everytime = true;

    public function apply_fix() {
        YoastSeoLlmsTxtFix::apply();
    }

    public function remove_fix() {
        YoastSeoLlmsTxtFix::remove();
    }
}

And register it in CompatibilityFactory::setup_targets():

YoastSeo::class => [ 'slug' => 'wordpress-seo/wp-seo.php' ],

Behavior

The filter redirects Yoast's file writes to wp-content/uploads/llms.txt, which is writable on all Pantheon environments. Yoast's internal logic treats a non-existent file as one it should always create, so the first WP-Cron run (or a settings save) after deploy will generate the file automatically — no pre-seeding required.

Caveat

The filter handles the write path, but llms.txt still needs to be accessible at the webroot URL (/llms.txt). Because wp-content/uploads is not the webroot, users will also need to commit a symlink to their codebase:

ln -s wp-content/uploads/llms.txt llms.txt

This is a one-time manual step that can't be automated by the mu-plugin (the codebase is read-only in Test/Live). The known issues docs cover this step but it might be worth highlighting in the plugin.