Hooks overview
Staatic exposes WordPress action and filter hooks for projects that need behavior beyond the settings screen. Use them when the desired behavior is site-specific, deployment-specific, or too conditional for a global option.
This section is split by the part of Staatic you are changing:
| Page | Use it for |
|---|---|
| Publication lifecycle hooks | Running code around publication tasks, changing task order, tuning batch sizes, and adjusting cleanup limits. |
| URL processing hooks | Deciding which URLs are crawled, how URLs are transformed, and how Staatic discovers URLs in HTML. |
| Extension hooks | Registering deployment methods, settings, crawl URL providers, transformers, and post-processors. |
Choosing a hook
Start from the outcome you want, not from the hook name.
| Goal | Start with |
|---|---|
| Send a notification after deployment finishes | staatic_publication_task_after |
| Run code every time a publication task is attempted | staatic_publication_task_any |
| Add or remove a publication task | staatic_publication_tasks |
| Add extra starting points to a publication | staatic_additional_urls, staatic_additional_paths, or staatic_crawl_url_providers |
| Prevent a URL from being crawled | staatic_should_crawl_url |
| Keep a URL unchanged in the generated static output | staatic_should_transform_url |
| Treat production URLs as local WordPress URLs while crawling | staatic_replace_live_urls |
| Add support for lazy-loading attributes | staatic_html_mapping_tags, staatic_html_mapping_style, or staatic_html_mapping_srcset |
| Register a custom deployment target | staatic_deployment_methods and staatic_deployment_strategy; see Custom deployment methods |
| Add a custom settings field | staatic_settings and optionally staatic_setting_groups |
Where hook code belongs
Put project-specific hook code in a small custom plugin or an MU plugin. Avoid adding it to a theme unless the behavior is truly theme-specific, because publication and deployment behavior should continue to work if the theme changes.
For quick experiments, use an MU plugin such as:
wp-content/mu-plugins/staatic-customizations.phpAccepted arguments
Several Staatic hooks pass more than one argument. WordPress only passes one argument to callbacks by default, so always set the accepted argument count when a hook documents multiple arguments.
add_filter( 'staatic_should_crawl_url', function ( $shouldCrawl, $url, $context ) {
return $shouldCrawl;
}, 10, 3 );For actions, the same rule applies:
add_action( 'staatic_publication_task_after', function ( $publication, $task ) {
// ...
}, 10, 2 );Practical constraints
Publication hooks can run from the WordPress admin background process, from WP-CLI, or from automation. Keep callbacks deterministic and avoid assumptions about a browser request.
Avoid echo, var_dump(), redirects, and direct HTML output in Staatic hooks. Use logging, update your own state, or return modified values instead.
Long-running callbacks can make publication slower or cause task timeouts. For external API calls, prefer short timeouts and idempotent retries.
If a hook changes crawl scope or URL transformation, publish to a preview or staging target first. Small URL decisions can affect thousands of discovered resources.