Hooks and Filters Reference

Most sites won’t need any of this — it’s here for theme developers and agencies handling an integration the Settings screen doesn’t already cover directly.

ariadne_related_post_ids

Filters the final, already-scored related-post IDs for a post — the same list the Related Posts block and Inline Related Post actually render, not the scoring candidates. Use this to apply editorial rules the Settings screen can’t express (never repeat an author back-to-back, boost a specific post to the top, drop anything older than a year), or to integrate with a personalization/A-B-testing layer that swaps in its own picks for a segment of traffic.

add_filter( 'ariadne_related_post_ids', function( $post_ids, $post_id, $count ) {
    // Example: never show post 123 as related, anywhere.
    return array_diff( $post_ids, array( 123 ) );
}, 10, 3 );

You can also call ariadne_get_related_post_ids( $post_id, $count = 0 ) directly — e.g. from a custom template tag — to read a post’s related-post IDs (already run through this same filter) without touching the block or shortcode output at all.

$related_ids = ariadne_get_related_post_ids( get_the_ID() );

ariadne_related_content_hook

Changes which WordPress action hook Related Posts defers to, when “Position vs. theme ad slots” is turned on and your theme isn’t SmartMag or Bunyad (the one theme this plugin auto-detects out of the box). Most sites can use the plain-text “Custom ad-hook name” field on the Settings screen instead of this filter directly — reach for the filter when you need to set the hook conditionally in code rather than as a fixed value.

add_filter( 'ariadne_related_content_hook', function() {
    return 'your_theme_after_content_hook';
} );

ariadne_related_content_priority

Sets the priority Ariadne uses when hooking into whatever ariadne_related_content_hook resolves to. Defaults to 20 — lower it if your theme’s own ad output needs to run even later than that.

add_filter( 'ariadne_related_content_priority', function() {
    return 5;
} );

ariadne_cron_loopback_sslverify

Ariadne’s background jobs use a self-request mechanism to keep processing without waiting on site traffic. That internal request skips strict SSL certificate verification by default, since local development environments commonly use a self-signed certificate. On a production host with a real, CA-signed certificate, restore strict verification:

add_filter( 'ariadne_cron_loopback_sslverify', '__return_true' );

ariadne_color_scheme_meta

Since 1.9.57, Ariadne no longer adds a <meta name="color-scheme"> tag to your pages. That tag affects the whole page, not just the related-posts block: for readers whose device is in dark mode, it switches the page’s form controls and scrollbars to dark. If your site relied on it (for example, to stop Android Chrome’s “force dark” setting from recoloring the block), return the value you want and Ariadne adds it on posts that show the block:

add_filter( 'ariadne_color_scheme_meta', function() {
    return 'dark light'; // or 'only light'
} );

ariadne_related_updated (action)

Fires when a post’s related list changes, including when a background recompute changes it without the post being saved. Ariadne already clears that post’s page in LiteSpeed Cache, WP Rocket, W3 Total Cache, WP Super Cache, SiteGround Speed Optimizer, Cache Enabler, FlyingPress and WP Fastest Cache. Hook this action to clear any other cache, such as a CDN.

add_action( 'ariadne_related_updated', function( $post_id, $new_ids, $old_ids ) {
    my_cdn_purge_url( get_permalink( $post_id ) );
}, 10, 3 );

ariadne_purge_page_cache

Return false to stop Ariadne clearing a post’s cached page when its related list changes, for example if your cache already expires pages on its own schedule.

add_filter( 'ariadne_purge_page_cache', '__return_false' );

ariadne_cron_loopback_args

Filters the request Ariadne sends to your own site to run background jobs. On a staging site behind HTTP password protection, that request is blocked, and Site Health says so. Add the login here:

add_filter( 'ariadne_cron_loopback_args', function( $args ) {
    $args['headers']['Authorization'] = 'Basic ' . base64_encode( 'user:password' );
    return $args;
} );

ariadne_background_jobs_paused

Pauses background jobs from code, the same as Settings → Matching → “Pause background jobs”. Useful on a staging copy, or during a scripted import.

add_filter( 'ariadne_background_jobs_paused', '__return_true' );

ariadne_voyage_daily_cap

Overrides the daily Voyage AI request limit from Settings → AI & API. Return 0 for no limit.

add_filter( 'ariadne_voyage_daily_cap', function() {
    return 200;
} );

ariadne_tick_time_limit

How many seconds one background batch may run before it stops and leaves the rest for the next batch. Defaults to 20. Lower it on a host with a short PHP time limit.

add_filter( 'ariadne_tick_time_limit', function() {
    return 10;
} );

ariadne_up_next_enabled

Return false to hide Up next on a post. Receives the post being read.

add_filter( 'ariadne_up_next_enabled', function( $show, $post_id ) {
    return has_category( 'sponsored', $post_id ) ? false : $show;
}, 10, 2 );

ariadne_up_next_post_id

Chooses the post Up next links to. Ariadne passes its own choice: the best related match (the inline boxes and the Related Posts block skip it), or the previous post in the same category when there are no related posts. Return another published post’s ID, or 0 to hide Up next.

add_filter( 'ariadne_up_next_post_id', function( $next, $post_id ) {
    $series_next = (int) get_post_meta( $post_id, 'series_next', true );
    return $series_next ? $series_next : $next;
}, 10, 2 );

Something not covered here?

Get in touch and describe what you’re trying to integrate with — most one-off theme integrations end up as a filter addition rather than a custom fork.