URL processing hooks

Use these hooks when Staatic is finding, evaluating, replacing, or rewriting URLs. These decisions directly affect the generated static site, so test changes with a preview or staging publication before using them in production.

Crawl versus transform

Staatic makes two related but separate decisions:

Decision	What it controls	Main hook
Crawl	Whether a URL is added to the crawl queue and fetched.	`staatic_should_crawl_url`
Transform	Whether a discovered URL is rewritten in the static output.	`staatic_should_transform_url`

Returning false from staatic_should_crawl_url prevents Staatic from crawling that URL. Returning false from staatic_should_transform_url keeps the URL unchanged in generated files.

Enable extended URL context

Some URL decisions depend on where a URL was found. Enable extended context when callbacks need HTML tag, attribute, or surrounding-code details.

`staatic_extended_url_context`

Arguments:

Argument	Type
`$enabled`	`bool`

Example:

add_filter( 'staatic_extended_url_context', '__return_true' );

Extended context can include values such as htmlTagName, htmlAttributeName, htmlElement, before, and after, depending on the extractor that found the URL.

Control crawling

`staatic_should_crawl_url`

Determines whether a resolved URL should be crawled.

Arguments:

Argument	Type
`$shouldCrawl`	`bool`
`$url`	`Psr\Http\Message\UriInterface`
`$context`	`array`

Example:

add_filter( 'staatic_should_crawl_url', function ( $shouldCrawl, $url, $context ) {
    $path = $url->getPath();

    if ( str_starts_with( $path, '/author/' ) ) {
        return false;
    }

    if ( preg_match( '#^/\d{4}/\d{2}/#', $path ) ) {
        return false;
    }

    if ( str_starts_with( $path, '/member-area/' ) ) {
        return false;
    }

    return $shouldCrawl;
}, 10, 3 );

`staatic_exclude_urls`

Filters the configured exclude URL rules before Staatic builds the URL evaluator chain.

Arguments:

Argument	Type
`$excludeUrls`	`array`
`$baseUrl`	`Psr\Http\Message\UriInterface`

Example:

add_filter( 'staatic_exclude_urls', function ( array $excludeUrls, $baseUrl ) {
    $excludeUrls[] = '/private/*';
    return $excludeUrls;
}, 10, 2 );

`staatic_url_evaluators`

Filters the evaluator chain used to decide whether URLs are internal, excluded, or otherwise crawlable.

Use this hook only when staatic_should_crawl_url and staatic_exclude_urls are not enough. Removing the default internal URL evaluator can make Staatic crawl URLs outside the intended site boundary.

Arguments:

Argument	Type
`$evaluators`	`Staatic\Crawler\UrlEvaluator\UrlEvaluatorInterface[]`

Control transformation

`staatic_should_transform_url`

Determines whether a discovered URL should be rewritten in the generated static output.

Arguments:

Argument	Type
`$shouldTransform`	`bool`
`$url`	`Psr\Http\Message\UriInterface`
`$foundOnUrl`	`Psr\Http\Message\UriInterface\|null`
`$context`	`array`

Use this when the page should still be crawled, but a particular link or endpoint should remain unchanged.

Example:

add_filter( 'staatic_should_transform_url', function ( $shouldTransform, $url, $foundOnUrl, $context ) {
    if ( str_contains( $url->getPath(), '/wp-admin/admin-ajax.php' ) ) {
        return false;
    }

    if ( ( $context['htmlAttributeName'] ?? '' ) === 'data-url' ) {
        return false;
    }

    return $shouldTransform;
}, 10, 4 );

When this filter returns false, Staatic keeps the original URL. If you need absolute URLs pointing to the static site instead, configure an absolute Destination URL or implement a custom transformer.

Replace live URLs while crawling

`staatic_replace_live_urls`

Since: v1.7.0

Filters the list of live or production site URLs that should be treated as the current dynamic WordPress site while crawling response bodies.

This is useful after a site has moved to a public production domain while WordPress remains on a private or origin URL.

Arguments:

Argument	Type
`$replaceLiveUrls`	`string[]`

Example:

add_filter( 'staatic_replace_live_urls', function ( $replaceLiveUrls ) {
    $replaceLiveUrls[] = 'https://www.example.com';
    return $replaceLiveUrls;
} );

`staatic_crawler_body_replacements`

Filters the final response-body replacement map used by the crawler.

Arguments:

Argument	Type
`$replacements`	`array`

Use this only when you need lower-level replacement control than staatic_replace_live_urls provides.

Adjust HTML URL discovery

Staatic extracts URLs from known HTML tags and attributes. These filters are useful for themes or plugins that store URLs in nonstandard attributes.

Hook	Use it for
`staatic_html_mapping_tags`	Add or remove tag-to-attribute URL extraction rules.
`staatic_html_mapping_style`	Add or remove style attributes that can contain URLs.
`staatic_html_mapping_srcset`	Add or remove attributes that should be parsed as `srcset` values.

Example:

add_filter( 'staatic_html_mapping_tags', function ( array $mapping ) {
    $mapping['div'][] = 'data-background-image';
    return $mapping;
} );

Other URL-related filters

Hook	Use it for
`staatic_site_url`	Override the dynamic WordPress site URL Staatic uses internally.
`staatic_forced_file_extensions`	Adjust file extensions that Staatic treats as assets during shallow publications.
`staatic_crawl_options`	Customize low-level crawler options.

Treat staatic_crawl_options as an advanced hook. It receives a Staatic\Crawler\CrawlOptions object and can affect concurrency, depth, asset handling, DOM parsing, and context collection.