Filters Reference

This is the complete reference for every public filter in the Hydrogen SEO WordPress plugin (Beta). Filters let you change what Hydrogen SEO outputs — titles, meta descriptions, schema markup, sitemaps, robots directives and more — without touching plugin code. Every signature below was verified against the plugin source; add snippets to a small custom plugin or your theme's functions.php.

A quick reminder on mechanics: a filter callback always receives a value, may receive extra context arguments, and must return the (possibly modified) value. When a filter passes more than one argument, pass the argument count as the fourth parameter of add_filter().

Titles and meta

hydrogen_seo_title

Filters the final SEO title string just before it is cached and printed. Receives one argument: the title (string).

add_filter( 'hydrogen_seo_title', function ( $title ) {
    if ( is_singular( 'product' ) ) {
        $title = 'Buy ' . $title;
    }
    return $title;
} );

hydrogen_seo_description

Filters the final meta description string before output. One argument: the description (string).

add_filter( 'hydrogen_seo_description', function ( $description ) {
    return trim( $description );
} );

hydrogen_seo_title_separator

Filters the separator used between title parts (for example between a post title and the site name) when a title is built without a template. One argument: the separator (string), default the Title Separator from Titles & Meta → General with a space on each side (' - ' out of the box). To change the separator everywhere, including %separator% in templates, use that setting instead.

// Use a pipe instead of a dash between title parts.
add_filter( 'hydrogen_seo_title_separator', function () {
    return ' | ';
} );

hydrogen_seo_description_length

Filters the maximum meta description length the plugin works with. One argument: the length (int), default 160.

add_filter( 'hydrogen_seo_description_length', function () {
    return 155;
} );

hydrogen_seo_variable_replacements

Filters the map of template variable tokens to replacement values before they are substituted into titles, descriptions and schema fields. Arguments: $replacements (array of '%token%' => 'value'), $post (WP_Post|null), $term (object|null). This is the filter to use when you want your own variables available everywhere template variables work.

// Add a %reading_time% variable usable in any title or description template.
add_filter( 'hydrogen_seo_variable_replacements', function ( $replacements, $post, $term ) {
    if ( $post instanceof WP_Post ) {
        $words                          = str_word_count( wp_strip_all_tags( $post->post_content ) );
        $replacements['%reading_time%'] = max( 1, (int) ceil( $words / 200 ) ) . ' min read';
    }
    return $replacements;
}, 10, 3 );

hydrogen_seo_titles_meta_default_settings

Filters the default settings array for the Titles & Meta module. One argument: $defaults (array).

hydrogen_seo_homepage_settings_defaults

Filters the default settings array for the Homepage SEO module. One argument: $defaults (array). See Homepage SEO for what these settings control.

hydrogen_seo_prepared_post_meta

Filters the fully merged SEO meta for a post after per-post meta, global settings and defaults are combined. Arguments: $meta (array), $post_id (int).

hydrogen_seo_prepared_term_meta

Same as above, for taxonomy terms. Arguments: $meta (array), $term_id (int).

hydrogen_seo_term_seo_defaults

Filters the default SEO structure applied to terms. One argument: the defaults array (derived from post defaults).

Schema

hydrogen_seo_schema_markup

Filters the generated JSON-LD schema array for a post before it is printed. Arguments: $schema (array), $post_id (int), $schema_type (string, for example Article). Return an empty array to suppress output for that post.

// Add a publisher logo to Article schema.
add_filter( 'hydrogen_seo_schema_markup', function ( $schema, $post_id, $schema_type ) {
    if ( 'Article' === $schema_type ) {
        $schema['publisher']['logo'] = [
            '@type' => 'ImageObject',
            'url'   => 'https://example.com/logo.png',
        ];
    }
    return $schema;
}, 10, 3 );

hydrogen_seo_generated_schema

Filters a schema array at generation time, right after the type-specific properties are assembled. Arguments: $schema (array), $post (WP_Post), $schema_type (string). Use this when you need the full post object rather than just the ID.

hydrogen_seo_schemas

Filters the complete list of schema objects the frontend will print (after variable replacement and empty-value cleanup). One argument: $schemas (array of schema arrays). Handy for appending an extra JSON-LD block site-wide.

// Inject a WebSite schema on the homepage.
add_filter( 'hydrogen_seo_schemas', function ( $schemas ) {
    if ( is_front_page() ) {
        $schemas[] = [
            '@context' => 'https://schema.org',
            '@type'    => 'WebSite',
            'name'     => get_bloginfo( 'name' ),
            'url'      => home_url( '/' ),
        ];
    }
    return $schemas;
} );

hydrogen_seo_schema_markup_post_types

Filters which post types the Schema Markup module applies to. One argument: array of post type slugs, default [ 'post', 'page' ].

add_filter( 'hydrogen_seo_schema_markup_post_types', function ( $post_types ) {
    $post_types[] = 'recipe';
    return $post_types;
} );

hydrogen_seo_schema_location_options

Filters the location options (site areas, special pages and post types) offered when choosing where a schema should display. One argument: $options (array grouped by category).

Sitemap

hydrogen_seo_sitemap_exclude_item

Filters whether an item is excluded from the XML sitemap. Arguments: $excluded (bool — true when the item's robots meta is set to noindex), $object_id (int), $type (string, post or term). See XML sitemaps for the settings-based approach.

// Keep an internal landing page out of the sitemap.
add_filter( 'hydrogen_seo_sitemap_exclude_item', function ( $excluded, $object_id, $type ) {
    if ( 'post' === $type && 42 === $object_id ) {
        return true;
    }
    return $excluded;
}, 10, 3 );

hydrogen_seo_sitemap_post_priority

Filters the <priority> value for a post. Arguments: $priority (string, defaults: pages 0.8, posts 0.6, everything else 0.5), $post_id (int).

add_filter( 'hydrogen_seo_sitemap_post_priority', function ( $priority, $post_id ) {
    return has_post_thumbnail( $post_id ) ? '0.9' : $priority;
}, 10, 2 );

hydrogen_seo_sitemap_post_images

Filters the image entries collected for a post (featured image plus images found in content). Arguments: $images (array of image data), $post_id (int).

hydrogen_seo_sitemap_url

Filters the sitemap URL used elsewhere (for example the Sitemap directive appended to robots.txt). One argument: the URL (string, default home_url( 'sitemap.xml' )).

hydrogen_seo_sitemap_index_xml

Filters the raw XML of the sitemap index. One argument: $xml (string).

hydrogen_seo_sitemap_post_type_xml

Filters the raw XML of a post-type sitemap. Arguments: $xml (string), $post_type (string), $page (int — the sitemap page number).

hydrogen_seo_sitemap_taxonomy_xml

Filters the raw XML of a taxonomy sitemap. Arguments: $xml (string), $taxonomy (string).

Video sitemap

These filters apply to the optional video sitemap. To keep a single post out without code, switch on Exclude from video sitemap in its SEO panel (stored as the hydrogen_seo_post_meta_video_sitemap_exclude meta key).

hydrogen_seo_video_sitemap_detected_videos

Filters the videos detected in a post while it is scanned. Arguments: $detected (array), $post (the post being scanned).

hydrogen_seo_video_sitemap_builder_meta_keys

Filters the page builder meta keys scanned for videos. One argument: $keys (array). Use it to add the meta key of a builder Hydrogen SEO does not read by default.

hydrogen_seo_video_sitemap_post_videos

Filters the final video entries for a post. Arguments: $videos (array), $post (the post).

hydrogen_seo_video_sitemap_exclude_post

Filters whether a post is left out of the video sitemap. Arguments: $excluded (bool), $post (the post).

// Keep posts in the "Members" category out of the video sitemap.
add_filter( 'hydrogen_seo_video_sitemap_exclude_post', function ( $excluded, $post ) {
    return has_category( 'members', $post ) ? true : $excluded;
}, 10, 2 );

hydrogen_seo_video_sitemap_xml

Filters the raw XML of a video sitemap page. Arguments: $xml (string), $page (int — the sitemap page number).

News sitemap

These filters apply to the optional news sitemap. To keep a single post out without code, switch on Exclude from Google News in its SEO panel (stored as the hydrogen_seo_post_meta_news_sitemap_exclude meta key).

hydrogen_seo_news_sitemap_publication_name

Filters the publication name printed in every news:publication entry. One argument: the name (string — the Publication setting, or the site title when that is empty).

hydrogen_seo_news_sitemap_language

Filters the language code of one article. Arguments: $language (string — the WPML or Polylang language when present, otherwise the site locale), $post (the post).

// Mark articles in the "Noticias" category as Spanish on a site without a translation plugin.
add_filter( 'hydrogen_seo_news_sitemap_language', function ( $language, $post ) {
    return has_category( 'noticias', $post ) ? 'es' : $language;
}, 10, 2 );

hydrogen_seo_news_sitemap_exclude_post

Filters whether a post is left out of the news sitemap. Arguments: $excluded (bool), $post (the post).

hydrogen_seo_news_sitemap_xml

Filters the raw XML of the news sitemap. One argument: $xml (string).

Robots

hydrogen_seo_robots_directives

Filters the array of robots meta directives (for example [ 'index', 'follow' ]) before they are printed as a <meta name="robots"> tag. One argument: $directives (array of strings). See robots meta settings for the UI equivalent.

// Force noarchive on search result pages.
add_filter( 'hydrogen_seo_robots_directives', function ( $directives ) {
    if ( is_search() ) {
        $directives[] = 'noarchive';
    }
    return array_unique( $directives );
} );

hydrogen_seo_robots_txt

Filters the final robots.txt content the plugin serves (whether it came from the built-in editor or was generated as a default). Arguments: $content (string), $output (string — WordPress's original robots.txt output), $public (bool).

add_filter( 'hydrogen_seo_robots_txt', function ( $content, $output, $public ) {
    if ( $public ) {
        $content .= "\nDisallow: /private-downloads/\n";
    }
    return $content;
}, 10, 3 );

hydrogen_seo_default_robots_txt

Filters the default robots.txt content used when no custom content is saved in the robots.txt editor. Arguments: $default (string), $public (bool).

hydrogen_seo_robots_data

Filters the data payload the robots editor screen works with. One argument: $data (array).

hydrogen_seo_robots_settings_defaults

Filters the default settings array for the site-wide Robots Settings module. One argument: $defaults (array).

hydrogen_seo_robots_sitemap_url

Filters the sitemap URL exposed to the robots editor. One argument: the URL (string).

llms.txt

hydrogen_seo_llms_txt_content

Filters the llms.txt content after it is loaded from storage (or defaults), before it is served. One argument: $content (string). llms.txt is a proposed convention for AI crawlers — see the llms.txt editor.

add_filter( 'hydrogen_seo_llms_txt_content', function ( $content ) {
    return $content . "\n## Contact\nFor licensing questions: ai@example.com\n";
} );

hydrogen_seo_default_llms_txt_content

Filters the default llms.txt content used before any custom content is saved (and after a reset). One argument: $content (string).

Metabox

hydrogen_seo_metabox_post_types

Filters the post types that get the Hydrogen SEO panel (the SEO Settings sheet in the editor). One argument: array of post type slugs — the enabled, public post types (default post and page).

// Show the SEO panel on a custom post type.
add_filter( 'hydrogen_seo_metabox_post_types', function ( $post_types ) {
    $post_types[] = 'portfolio';
    return $post_types;
} );

hydrogen_seo_metabox_taxonomies

Filters the taxonomies that get SEO fields on their term edit screens. One argument: array of taxonomy slugs (default category and post_tag).

hydrogen_seo_metabox_localize_data

Filters the data localized to the metabox React app (API URLs, nonces, variables and similar). One argument: $base_data (array).

Analysis

hydrogen_seo_seo_analysis_post_types

Filters which post types get an SEO score. One argument: array of post type slugs, default every public post type except attachment. Pairs naturally with hydrogen_seo_metabox_post_types — see on-page SEO analysis.

add_filter( 'hydrogen_seo_seo_analysis_post_types', function ( $post_types ) {
    $post_types[] = 'portfolio';
    return $post_types;
} );

hydrogen_seo_seo_analysis_results

Filters the computed analysis results (content length, word count, keyword density, readability, link/image/heading stats). Arguments: $analysis (array), $content (string), $focus_keyword (string).

// Add a custom metric to the analysis payload.
add_filter( 'hydrogen_seo_seo_analysis_results', function ( $analysis, $content, $focus_keyword ) {
    $analysis['shortcode_count'] = substr_count( $content, '[' );
    return $analysis;
}, 10, 3 );

Settings and advanced

hydrogen_seo_enable_frontend

Return false to disable all of Hydrogen SEO's frontend output (titles, meta, schema). One argument: bool, default true. Useful on headless WordPress installs — see Extending Hydrogen SEO for the full recipe.

add_filter( 'hydrogen_seo_enable_frontend', '__return_false' );

hydrogen_seo_sanitize_settings

Filters the sanitized settings array before it is stored. Arguments: $clean (array — sanitized settings), $settings (array — raw input).

hydrogen_seo_admin_localize_data

Filters the data localized to the admin dashboard React app (REST URL, route map, nonces, version, supported variables and so on). One argument: $data (array).

hydrogen_seo_filter_changed_fields

Filters which per-post fields are considered "changed" relative to global settings when saving SEO data (only changed fields are persisted). Arguments: $changed_fields (array), $meta_data (array), $context (string, post or term), $id (int).

hydrogen_seo_agent_url

Filters the base URL of the Hydrogen AI agent service (default https://hydrogenseo.com/api/agent). One argument: the URL (string). Mostly useful for staging environments.

hydrogen_seo_backend_url

Filters the base URL of the hydrogenseo.com SaaS backend the plugin talks to (default https://hydrogenseo.com/api). One argument: the URL (string).

Related reading

• Actions Reference
• The Plugin REST API
• Extending Hydrogen SEO
• Template variables
• XML sitemaps
• The video sitemap
• The news sitemap