BugWP logo BugWP
Back to Community
Home / Community / Plugin → Rank math seo

How to Add Custom URLs and Sitemaps in Rank Math SEO

23 threads Sep 9, 2025 Plugin → Rank math seo

Content

Many WordPress users migrating from other SEO plugins or implementing advanced multilingual setups find that they need to add custom URLs to their Rank Math-generated sitemap. This is a common task for including PDF files, filter pages, or external sitemap indexes that aren't part of the standard WordPress content structure.

Why Custom URLs Are Not Included by Default

Rank Math SEO automatically generates sitemaps for standard WordPress content types (posts, pages, custom post types) that are registered within the database. Dynamically generated URLs, such as those created by filter parameters or files stored in specific directories, are not included because they are not recognized as standard content entities. This design ensures optimal performance and avoids sitemap bloat with potentially infinite dynamic URL combinations.

Common Solutions for Adding Custom URLs

1. Adding Individual URLs with a Filter

For adding specific, known URLs (like a set of PDFs), you can use the rank_math/sitemap/entry filter. The code snippet below demonstrates how to add all PDF files from a specific directory to the post sitemap. It's crucial to use the correct filter and ensure the file paths and URLs are accurately constructed.

// Add custom URLs to the sitemap
add_filter( 'rank_math/sitemap/entry', 'add_custom_urls_to_sitemap', 10, 2 );
function add_custom_urls_to_sitemap( $url, $type ) {
    // Check if the type is post
    if ( 'post' === $type ) {
        // Define the custom folder where the PDF files are stored
        $custom_folder = '/wp-content/uploads/custom-folder/';
        // Get the list of PDF files in the custom folder
        $pdf_files = glob( ABSPATH . $custom_folder . '*.pdf' );
        // Loop through each PDF file
        foreach ( $pdf_files as $pdf_file ) {
            // Get the file name
            $file_name = basename( $pdf_file );
            // Get the file URL
            $file_url = home_url( $custom_folder . $file_name );
            // Add the file URL to the sitemap array
            $url[] = array(
                'loc' => $file_url,
                'lastmod' => date( 'c', filemtime( $pdf_file ) ),
                'changefreq' => 'monthly',
                'priority' => 0.6,
            );
        }
    }
    // Return the modified sitemap array
    return $url;
}

2. Adding an Entire External Sitemap Index

If you need to add a link to a completely separate sitemap file (e.g., one generated by another tool), you should use the rank_math/sitemap/index filter to add a new <sitemap> section to the main sitemap index. Note that the official Rank Math documentation recommends a specific method for this.

// Add an external sitemap to the sitemap index
add_filter( 'rank_math/sitemap/index', function( $xml ) {
    $xml .= '<sitemap>
        <loc>http://example.com/new-sitemap.xml</loc>
        <lastmod>2020-09-14T20:34:15+00:00</lastmod>
    </sitemap>';
    return $xml;
}, 11 );

Important: For a more robust solution, it is highly recommended to follow the guide for creating custom sitemaps as referenced in the support threads.

3. Programmatically Clearing the Sitemap Cache

When content is added programmatically (e.g., via wp_insert_post), the sitemap may not update immediately due to caching. To force a refresh, you need to clear Rank Math's sitemap cache. The following code can be run after bulk programmatic operations.

// Clear the Rank Math sitemap cache
delete_transient( 'rank_math_sitemap_cache' );

Important Considerations and Limitations

  • Multilingual Incompatibility: A recurring theme in the threads is limited compatibility with some multilingual plugins, notably Polylang. The Rank Math team has stated they have submitted compatibility code to the Polylang development team, but full integration is pending. This can result in only default language terms appearing in taxonomy sitemaps. Users experiencing this may need to seek a solution from the translation plugin's support or consider using a compatible alternative.
  • Dynamic URLs: Rank Math does not add purely dynamic URLs, like those with filter parameters (?filter=value), to the sitemap by default, as they are not stored posts in the database. The provided filter method is the primary workaround for this.
  • Caching Conflicts: If your sitemap URLs return a 404 error or do not display correctly, it is often due to server or plugin caching. Sitemaps must be excluded from caching. Review your caching plugin's settings (e.g., FlyingPress) to exclude all XML files and ensure your server's rewrite rules are correctly configured, especially on Nginx.

By using these filters and understanding the limitations, you can effectively extend your Rank Math sitemap to include the necessary URLs for optimal search engine indexing.

Related Support Threads Support