Hooks reference

This page lists the public filters and actions in Anansi SEO 0.5.11, grouped by feature. For each hook it says when it runs, what it receives and what it should return. Most page-output filters run only when Anansi builds that output: when it is in charge (live mode, no other SEO plugin) or on a signed preview request. Many hooks have a Rank Math twin that Anansi fires with the same arguments; those are listed in Rank Math compatibility hooks at the end.

Hooks marked low-level mirror a Rank Math hook of the same shape. They work, but they are close to Anansi’s internals and are more likely to change than the others.

Contents

• Head and page output
• Title variables
• Open Graph and Twitter
• Schema (JSON-LD graph)
• Video schema
• Content blocks
• Breadcrumbs
• Sitemaps
• News sitemap
• Redirects and 404 log
• Internal link suggestions
• Crawlers, llms.txt and IndexNow
• Editor
• Tweaks
• Last updated line
• Admin screens and dashboard
• Settings export, import and snapshots
• Activation
• Abilities
• Google module
• Rank Math compatibility hooks

Head and page output

anansi/head/tags (filter)

Collects the tags for Anansi’s head block. Runs once per page while Anansi builds its wp_head output.

Returns array[].

Anansi’s own tags use these orders: <title> 1, description 6, robots 10, canonical 20, prev/next 21 and 22, Open Graph and Twitter 30, verification tags 90. Items with empty html are dropped.

add_filter( 'anansi/head/tags', function ( $tags ) {
    $tags[] = array(
        'order' => 25,
        'html'  => '<meta name="theme-color" content="#0f172a" />',
    );
    return $tags;
} );

Escape everything you put in html. Anansi prints it as given.

anansi/head (action)

Fires inside Anansi’s head block, after the tags from anansi/head/tags and before the closing marker. Anansi’s JSON-LD prints here at priority 90.

add_action( 'anansi/head', function ( $preview ) {
    echo '<link rel="author" href="' . esc_url( home_url( '/humans.txt' ) ) . '" />' . "\n";
} );

anansi/title_raw (filter)

The page title before escaping. Runs after Anansi resolved the template and variables (and capitalised it, if that setting is on), before the page number is added.

Returns string. Return '' to leave WordPress’s own title.

Rank Math twin: rank_math/frontend/title.

add_filter( 'anansi/title_raw', function ( $title ) {
    if ( is_singular( 'event' ) ) {
        $title .= ' | Tickets';
    }
    return $title;
} );

anansi/title/add_page_number (filter)

Whether to add “Page N of M” to the title of page 2 and later when the title does not already show it.

Returns bool.

anansi/title (filter)

The plain-text title Anansi hands to WordPress through pre_get_document_title (priority 15) in live mode, for themes that call wp_get_document_title(). Anansi fills it from its own title at default priority.

Returns string. To change the title, prefer anansi/title_raw, which also changes the <title> tag in Anansi’s head block.

anansi/title_separator (filter)

The separator used for %sep%.

Returns string.

anansi/description (filter)

The meta description before escaping.

Returns string. Return '' for no description tag.

Rank Math twin: rank_math/frontend/description.

anansi/robots (filter)

The robots directives for the page.

Returns array.

Rank Math twin: rank_math/frontend/robots.

add_filter( 'anansi/robots', function ( $robots ) {
    if ( is_tag() ) {
        $robots['index']  = 'noindex';
        $robots['follow'] = 'follow';
    }
    return $robots;
} );

anansi/advanced_robots (filter)

The max-* directives. Runs only when the page is indexable and not nosnippet.

Returns array. The result is merged into the robots list.

Rank Math twin: rank_math/frontend/advanced_robots.

anansi/canonical (filter)

The canonical URL. Anansi prints no canonical on noindex pages.

Returns string. Return '' for no canonical tag.

Rank Math twin: rank_math/frontend/canonical.

anansi/prev_rel_link and anansi/next_rel_link (filters)

The full <link rel="prev"> / <link rel="next"> tag HTML on paginated pages.

Returns string. Return '' to drop it. Only <link> tags with href and rel survive.

Rank Math twins: rank_math/frontend/prev_rel_link, rank_math/frontend/next_rel_link.

anansi/disable_adjacent_rel_links (filter)

Returns bool. true turns off rel prev/next.

add_filter( 'anansi/disable_adjacent_rel_links', '__return_true' );

anansi/meta/sources (filter)

The meta keys Anansi reads for a field, in order. Runs every time Anansi reads a post, term or user field.

Returns string[]. The first stored, non-empty value wins.

add_filter( 'anansi/meta/sources', function ( $keys, $type, $key ) {
    if ( 'post' === $type && 'title' === $key ) {
        $keys[] = '_mytheme_seo_title';
    }
    return $keys;
}, 10, 3 );

See theme-integration.md.

anansi/disable_primary_term (filter)

When Anansi is in charge it moves a post’s primary term to the front of get_the_terms() results.

Returns bool. true keeps WordPress’s order.

anansi/webmaster/{id} (filter)

The content of one site verification tag on the front page. {id} is one of google_verify, bing_verify, baidu_verify, yandex_verify, pinterest_verify, norton_verify.

Returns string. '' prints no tag.

Rank Math twin: rank_math/webmaster/{id}.

Title variables

anansi/vars/replacements (filter)

All variable replacements for one template, just before they are applied.

Returns array.

anansi/vars/{name} (filter)

Value for a variable Anansi does not know. {name} is the lower-case variable name without percent signs.

Returns string\|null. null becomes an empty string.

// %price% and %price(EUR)% in any title or description template.
add_filter( 'anansi/vars/price', function ( $value, $args, $object ) {
    if ( ! $object instanceof WP_Post ) {
        return $value;
    }
    $price = get_post_meta( $object->ID, '_price', true );
    return '' === $price ? $value : trim( ( $args ? $args : '$' ) . ' ' . $price );
}, 10, 3 );

Open Graph and Twitter

All of these run while Anansi builds its social tags. Each has a Rank Math twin with the rank_math/ prefix instead of anansi/ (for example rank_math/opengraph/facebook/og_title).

anansi/opengraph/{network}/{property} (filter)

One filter per tag value. {network} is facebook, twitter or slack. {property} is the tag name with : changed to _.

Returns scalar. An empty value drops the tag.

add_filter( 'anansi/opengraph/facebook/og_title', function ( $title ) {
    return is_front_page() ? 'Acme: tools for makers' : $title;
} );

Other Open Graph filters

// Use a branded image when a page has none.
add_filter( 'anansi/opengraph/facebook/image', function ( $url ) {
    return '' === $url ? get_theme_file_uri( 'assets/share.png' ) : $url;
} );

Schema (JSON-LD graph)

Anansi prints one <script type="application/ld+json" class="anansi-schema"> with an @graph, on the anansi/head action at priority 90.

anansi/json_ld (filter)

Builds the graph. Your callback gets the graph so far and returns it.

Returns array.

Anansi’s own steps run on the same hook:

Callbacks added to rank_math/json_ld run in the same chain (see the compatibility section). Keys are dropped when the graph is printed. Nodes that only have @type, and empty values, are removed.

Run at priority 20 to see Anansi’s main nodes. Give your own nodes an @id; the linking step at 99 only touches schema-* and richSnippet.

add_filter( 'anansi/json_ld', function ( $data, $jsonld ) {
    if ( ! is_singular( 'product' ) ) {
        return $data;
    }
    $url = get_permalink();
    $data['acmeProduct'] = array(
        '@type' => 'Product',
        '@id'   => $url . '#product',
        'name'  => get_the_title(),
        'url'   => $url,
    );
    if ( isset( $data['publisher']['@id'] ) ) {
        $data['acmeProduct']['brand'] = array( '@id' => $data['publisher']['@id'] );
    }
    return $data;
}, 20, 2 );

A full example is in theme-integration.md.

anansi/schema/validated_data (filter)

The whole graph after empty values were removed, just before printing.

Returns array.

Other schema filters

All have a rank_math/ twin with the same name after the prefix.

// News posts are NewsArticle by default.
add_filter( 'anansi/schema/default_type', function ( $type, $post_type, $post_id ) {
    return has_category( 'news', $post_id ) ? 'NewsArticle' : $type;
}, 10, 3 );

Video schema

add_filter( 'anansi/video/creator_type', function () {
    return 'Organization';
} );

Content blocks

These run for Rank Math’s FAQ (rank-math/faq-block) and HowTo (rank-math/howto-block) blocks, which Anansi supports after Rank Math is gone. The Rank Math twins of the schema/block/* and schema/nested_blocks filters run without Rank Math’s own callbacks.

Breadcrumbs

Breadcrumbs are on when the General setting is on, or when the theme declares add_theme_support( 'anansi-breadcrumbs' ) or add_theme_support( 'rank-math-breadcrumbs' ).

anansi/breadcrumb/items (filter)

The breadcrumb trail. Used for the BreadcrumbList schema and the compatibility breadcrumb functions.

Returns array. Crumbs with an empty URL or hide_in_schema are left out of the schema.

Rank Math twin: rank_math/frontend/breadcrumb/items.

add_filter( 'anansi/breadcrumb/items', function ( $crumbs ) {
    if ( is_singular( 'docs' ) ) {
        array_splice( $crumbs, 1, 0, array( array( 'Docs', home_url( '/docs/' ), 'hide_in_schema' => false ) ) );
    }
    return $crumbs;
} );

anansi/breadcrumb/main_term (filter)

The term shown for a post when its post type uses a primary taxonomy.

Returns WP_Term. Anything else drops the term crumbs.

Rank Math twin: rank_math/frontend/breadcrumb/main_term.

anansi/breadcrumb/html (filter)

The HTML printed by the compatibility functions and shortcodes (see functions.md).

Returns string.

Sitemaps

Anansi serves /sitemap_index.xml, /{type}-sitemap.xml, /{type}-sitemap{n}.xml and the stylesheet when it is in charge. Every anansi/sitemap/{x} filter below has a Rank Math twin rank_math/sitemap/{x}.

anansi/sitemap/index/entry (filter)

One entry in the sitemap index.

Returns array\|false. A falsy value removes the entry.

// No author sitemap in the index.
add_filter( 'anansi/sitemap/index/entry', function ( $entry, $kind ) {
    return 'author' === $kind ? false : $entry;
}, 10, 2 );

anansi/sitemap/entry (filter)

One URL in a post, term or author sitemap (also used to filter HTML sitemap items).

Returns array\|false. An empty value removes the URL.

anansi/sitemap/index (filter)

Raw XML added at the end of the sitemap index, before </sitemapindex>. Anansi’s news sitemap uses it.

Returns string of <sitemap>…</sitemap> elements.

anansi/sitemap/{type}/content (filter)

Body of a sitemap type that no built-in provider handles, for example /custom-sitemap.xml ({type} = custom). Anansi adds the XML declaration and stylesheet line in front.

Returns string, a full <urlset>…</urlset>. '' gives a 404.

See theme-integration.md for a full example.

Exclusions

add_filter( 'anansi/sitemap/exclude_taxonomy', function ( $exclude, $taxonomy ) {
    return 'post_tag' === $taxonomy ? true : $exclude;
}, 10, 2 );

URLs and images

Caching and response

The cache never serves stale copies: any change to posts, terms, users, SEO meta or settings starts a new cache generation. wp anansi sitemap flush clears it by hand.

HTML sitemap

Low-level sitemap hooks

These mirror Rank Math’s sitemap internals one to one.

News sitemap

anansi/news_sitemap/items (filter)

The posts listed in /news-sitemap.xml, after Anansi’s checks (last 48 hours, eligible post types, not excluded).

Returns WP_Post[].

add_filter( 'anansi/news_sitemap/items', function ( $items ) {
    return array_filter( $items, function ( $post ) {
        return ! has_tag( 'sponsored', $post );
    } );
} );

Redirects and 404 log

Redirects run on the front end when Anansi is in charge.

The Rank Math twins of pre_search and get_clean_pattern only run when Rank Math is not active.

// Send every old /shop/ URL to the new store.
add_filter( 'anansi/redirection/pre_search', function ( $pre, $uri ) {
    if ( null === $pre && 0 === strpos( $uri, 'shop/' ) ) {
        return array( 'url_to' => 'https://store.example.com/', 'header_code' => 301 );
    }
    return $pre;
}, 10, 2 );

Internal link suggestions

// Never suggest posts in the "Archive" category.
add_filter( 'anansi/links/exclude', function ( $exclude, $post_id ) {
    return $exclude || has_category( 'archive', $post_id );
}, 10, 2 );

Crawlers, llms.txt and IndexNow

robots.txt and AI crawlers

add_filter( 'anansi/crawlers/ai_bots', function ( $bots ) {
    $bots['ExampleBot'] = array( 'group' => 'training', 'vendor' => 'Example Inc.', 'note' => '' );
    return $bots;
} );

llms.txt

llms.txt is served at /llms.txt when Anansi is in charge and the setting is on. The Rank Math twins (rank_math/llms_txt/…) run only when Rank Math is not active.

The llms.txt body is cached. Saving General or Crawlers settings clears it.

IndexNow

Editor

Schema builder

// Add a "Course" form to the schema editor.
add_filter( 'anansi/schema_builder/types', function ( $specs ) {
    $specs['course'] = array(
        'type'        => 'Course',
        'label'       => 'Course',
        'description' => 'A course you teach.',
        'rich'        => false,
        'groups'      => array(
            array(
                'label'  => 'Basics',
                'fields' => array(
                    array( 'key' => 'name', 'label' => 'Name', 'kind' => 'text', 'level' => 'required', 'default' => '%title%' ),
                    array( 'key' => 'provider.name', 'label' => 'Provider', 'kind' => 'text', 'default' => '%org_name%' ),
                ),
            ),
        ),
        'objects'     => array( 'provider' => 'Organization' ),
    );
    return $specs;
} );

// Hide Anansi's editor for a post type that is never public in search.
add_filter( 'anansi/editor/post_types', function ( $types ) {
    return array_values( array_diff( $types, array( 'landing' ) ) );
} );

Tweaks

Unless noted, each has a rank_math/ twin with the same name after the prefix.

Last updated line

The optional “Last updated” line (Titles & Meta → Last updated line). It prints only while Anansi is in charge, on the singular page’s own post in the main loop. Feeds, REST, admin, excerpts and password-protected posts never get it. The date is the post’s modified date (never earlier than the publish date), the same date as the Article schema’s dateModified, so “Lock modified date” also keeps the line’s date. No Rank Math twins.

// Hide the line on one category.
add_filter( 'anansi/last_updated/show', function ( $show, $post ) {
    return $show && ! has_category( 'news', $post );
}, 10, 2 );

Admin screens and dashboard

anansi/admin/sections (filter)

Adds or changes sections on an Anansi settings page.

Returns array.

A field is an array with key (required), type and label, plus optional help, default, options (for select, radio, chips), option (store in another option; it is registered and saved with the page), placeholder, min, max, rows and show_if. Types include text, textarea, number, url, email, switch (alias toggle), select, radio, chips, code, lines, media and heading. Values are sanitised by type. When two sections define the same option key, the first one wins.

add_filter( 'anansi/admin/sections', function ( $sections, $page ) {
    if ( 'general' !== $page ) {
        return $sections;
    }
    $sections['acme'] = array(
        'title'  => 'Acme add-on',
        'desc'   => 'Settings for the Acme integration.',
        'fields' => array(
            array(
                'key'     => 'acme_enabled',
                'option'  => 'acme_seo',
                'type'    => 'switch',
                'default' => 'off',
                'label'   => 'Add Acme data to the schema',
            ),
        ),
    );
    return $sections;
}, 10, 2 );

anansi/admin/sanitized (filter)

Values about to be saved from an Anansi settings page, per option.

Returns array.

anansi/dashboard/cards (action)

Fires on the Anansi dashboard (needs manage_options) inside the main column, above the page preview card. Print your own card markup. The Google module uses it.

add_action( 'anansi/dashboard/cards', function () {
    echo '<section class="an-card"><h2>Acme</h2><p>All good.</p></section>';
} );

Settings export, import and snapshots

Activation

anansi/activate (action)

Fires when Anansi is activated, after its settings are seeded and before rewrite rules are flushed. Modules create tables and add rewrite rules here. No parameters.

add_action( 'anansi/activate', function () {
    // Anansi was just activated: set up the add-on's defaults.
    add_option( 'acme_seo', array( 'acme_enabled' => 'off' ) );
} );

It runs in the request that activates Anansi, so only code that is already loaded then (another active plugin, or the active theme) can hook it.

Abilities

anansi/abilities/post_updated (action)

Fires after the anansi/update-post-seo ability changed at least one field.

add_action( 'anansi/abilities/post_updated', function ( $post_id, $changed ) {
    error_log( sprintf( 'AI tool changed %s on post %d', implode( ', ', $changed ), $post_id ) );
}, 10, 2 );

See rest-and-abilities.md.

Google module

The Google module (Search Console and the YouTube Data API) has no public filters or actions. It adds its dashboard card through anansi/dashboard/cards and two REST routes, documented in rest-and-abilities.md.

Rank Math compatibility hooks

Code written for Rank Math often hooks rank_math/… filters. So that this code keeps working after the switch, Anansi fires the matching Rank Math hook right after its own, with the same arguments. Your anansi/… callback runs first, then the rank_math/… callbacks see the result.

When the Rank Math name is fired depends on the hook:

• Rank Math not active, or a signed preview request. This covers most output hooks, so a preview shows what your Rank Math code will do after the switch.
• Rank Math not active only. These hooks change things outside the page head (files, requests, redirects), so they never run twice while Rank Math still runs.
• Merged into Anansi’s graph. Callbacks on rank_math/json_ld run inside Anansi’s schema graph.

If a Rank Math hook is not listed here, Anansi does not fire it.

Fired when Rank Math is not active, or on a preview request

Fired only when Rank Math is not active

Content blocks

Anansi registers its own renderer for Rank Math’s FAQ and HowTo blocks only while Rank Math is not active. Inside it, these always fire:

rank_math/schema/block/before_filter, rank_math/schema/nested_blocks and rank_math/schema/block/{name} run inside Anansi’s graph without Rank Math’s own callbacks, so a preview never adds the same FAQ twice.

Schema graph: rank_math/json_ld

Anansi does not fire rank_math/json_ld as a separate filter. When it builds its graph, it takes every callback on rank_math/json_ld and every callback on anansi/json_ld, at their own priorities, and runs them in one chain. Callbacks that belong to Rank Math’s own classes are skipped, because Anansi does that work itself. The second argument is Anansi’s schema object, which has the can_add_global_entities() method and the public $post, $post_id and $parts properties that Rank Math callbacks commonly read.

Action: rank_math/head

After its head block, Anansi fires do_action( 'rank_math/head' ) when the request is not a preview and Rank Math is not active. Nothing is printed. Themes that check did_action( 'rank_math/head' ) to see whether an SEO plugin printed the tags will then step aside.

Shared filter: wp_helpers_is_affiliate_link

The external-links tweak reads wp_helpers_is_affiliate_link (bool $is_affiliate, string $url), the shared filter Rank Math and affiliate plugins use, to spot affiliate links.