Advanced Settings

• Logging
• Work Directory
• Network
  • HTTP Timeout
  • HTTP Delay
  • HTTP Concurrency
  • Downgrade HTTPS to HTTP
• HTTP Authentication
  • Username
  • Password
• SSL Certificates
  • Verification
  • CA Bundle Path
• Crawler
  • Custom Origin URL
  • Page Not Found Path
  • Process page not found resources
  • Enforce lowercase URLs
  • HTML DOM parser
• Publication Task Timeout
• Publication Time Limit
• Publish Changes
  • Update Archive Pages
  • Exclude Specific Taxonomies
  • Include Taxonomy Pagination
  • Exclude Author Archives
  • Include Author Pagination
  • Exclude Date Archives
  • Include Date Pagination
  • Pagination Limit
  • Additional URLs
• Plugin Uninstall
  • Delete plugin settings
  • Delete plugin data

The Advanced Settings allow you to tweak and tune the way Staatic works.

Logging

The logging level determines how much information is captured during publications. It affects both troubleshooting and publication performance.

• No logging: disables Staatic logging. Use only when logging is unnecessary.
• Minimal logging: records important publication events and errors. This is the recommended value for everyday operation.
• Detailed logging: includes crawler and deployment events, offering more insight for problem-solving with moderate performance impact.
• Extensive logging: captures comprehensive details including debug messages for in-depth troubleshooting, significantly affecting performance.

By default Logging is set to Minimal Logging. We recommend increasing the level of logging only while troubleshooting.

Work Directory

While publishing the static version of your WordPress site, a copy of your dynamic WordPress site is crawled and converted into static files. These files are stored in the work directory. Depending on the Staatic features and deployment method you use, other temporary files are stored there as well.

By default, the Work Directory is set to the WordPress uploads base directory plus /staatic, for example /wp-content/uploads/staatic. Depending on filesystem permissions, you may need to choose another directory.

Staatic creates the work directory during publication setup if it does not exist. Generated resources are stored under a resources subdirectory; publication setup fails if the work or resource directory cannot be created.

The work directory is excluded from Additional Paths processing by default. It is not removed automatically when uninstalling the plugin.

Network

At various stages during a publication, Staatic needs to perform HTTP requests, for example to crawl your dynamic WordPress site or to query our API to enable form handling or search. These settings can be changed to improve publication performance as well as limit the load on your server.

HTTP Timeout

By default the HTTP Timeout is set to 60 seconds. Staatic uses this value for both connection timeout and total request timeout. Retry handling covers HTTP 502, 503, and 429 responses, but not request timeouts.

HTTP Delay

By default the HTTP Delay is set to 0 milliseconds. If the value is above 0, requests are delayed by that number of milliseconds.

This can be used to decrease load on the server that hosts your dynamic WordPress site and can be useful on shared servers with multiple sites where the performance of other sites would otherwise be affected negatively.

HTTP Concurrency

By default the HTTP Concurrency is set to 4 concurrent HTTP requests. Staatic uses this for crawler concurrency and HTTP client host connections, and some deployment methods also use it for upload concurrency.

Be careful not to set this value too high or it may negatively impact the overall server performance. Depending on the specifications of the server, any value between 1 and 8 should be safe.

Staatic accepts whole numbers of 1 or higher. A value below 1, or a value that is not a number, is reported as a settings error and stored as 1. A stored value of 0 is also read as 1, because a concurrency of zero would leave the crawler with nothing to do.

Downgrade HTTPS to HTTP while crawling site

By default, Downgrade HTTPS to HTTP is disabled. Enabling this option causes internal crawl requests from Staatic to the WordPress instance to be forced over the HTTP protocol.

This option can be enabled in cases where WordPress is behind an HTTPS-terminating load balancer. This is only an issue when WordPress itself is not directly available via HTTPS (the external load balancer takes care of that) and the site address resolves to this local WordPress instance that only accepts HTTP.

The downgrade applies only to internal crawl requests. It rewrites the request scheme from https to http; it does not change the host or path and does not apply to external API or deployment requests.

HTTP Authentication

If you are using HTTP (basic) authentication to restrict access to your dynamic WordPress installation, Staatic requires a valid username and password combination. Otherwise it is unable to crawl your dynamic site successfully.

Note: we recommend that you set up a dedicated account for Staatic, so publications keep working when a regular user changes their username or password.

These credentials are used only for internal crawl requests. They can also be configured with STAATIC_HTTP_AUTH_USERNAME and STAATIC_HTTP_AUTH_PASSWORD; environment-provided values lock the settings UI unless STAATIC_DISABLE_ENV is set. The saved password is stored encrypted.

Username

The username for the HTTP authentication.

Password

The password for the HTTP authentication.

SSL Certificates

These settings determine if and how SSL certificates are verified during requests.

Verification

This setting describes the SSL certificate verification behavior of a request.

• Set to “Enabled” to enable SSL certificate verification and use the default CA bundle provided by the operating system.
• Set to “Disabled” to disable certificate verification (this is insecure!).
• Set to “Enabled using custom certificate” to provide the path to a CA bundle to enable verification using a custom certificate.

By default, the SSL certificate Verification behavior is set to “Enabled”. If your server uses self-signed certificates, change its value to “Enabled using custom certificate” or “Disabled”.

Note: setting the value to “Disabled” disables SSL certificate verification completely and is insecure. Use with caution!

When using a custom certificate, Staatic expects a valid local CA bundle path. If the path cannot be resolved, Staatic reports a settings error and requests fall back to normal verification behavior.

CA Bundle Path

This setting is only relevant when “Verification” is set to “Enabled using custom certificate” and should be the path to the certificate, for example “/path/to/cert.pem”.

Crawler

These settings allow you to change certain aspects of the crawler component. The crawler component is responsible for crawling all pages and assets of your dynamic site and preparing them for further processing.

Custom Origin URL

The Custom Origin URL setting specifies the entry point for the crawling process, ideally the homepage of your dynamic WordPress site. Use it when the crawler needs to start from a different URL, for more control over which content is included in the static site.

By default, the crawler uses the WordPress site’s address, configured in WP-Admin > Settings > General > Site Address (URL), as its starting point. Specify a different URL to start elsewhere, for example for an unusual site structure or a staging environment.

Staatic resolves the origin URL in this order: STAATIC_SITE_URL, the saved Custom Origin URL setting, then the WordPress site address. The resolved URL is filtered through staatic_site_url.

Page Not Found Path

This is the page Staatic crawls to create the 404 (page not found) page.

By default the Page Not Found Path is the WordPress URL path plus /404_not_found/. For a root-installed site this is /404_not_found/; for WordPress installed under /blog/, it becomes /blog/404_not_found/. If you have a specific 404 page on your dynamic WordPress site, e.g. /my_custom_404.html, then feel free to change the path here.

Process page not found resources

By default Process page not found resources is disabled. When enabled, in addition to the configured page not found page, other resources with a 404 status code will be included in the build as well.

In most cases having a single 404 page not found resource deployed is sufficient, since this is usually configured to be the shared 404 page used by the web server. If you have unique 404 pages for specific URLs, you can enable this setting to have them processed and deployed as well.

Enforce lowercase URLs

By default Enforce lowercase URLs is disabled. When enabled, all internal links, resources, and references in the static version of your site use lowercase URLs.

This keeps your URLs consistent and helps prevent duplicate content: search engines may treat URLs that differ only in case as separate pages, which can affect search rankings.

HTML DOM parser

The HTML DOM (Document Object Model) parser is responsible for understanding and manipulating the HTML structure of posts and pages in order to allow the static version of your site to be generated.

Due to the nature of the HTML DOM, different HTML DOM parsers all handle HTML slightly differently and also vary in performance. In order to support as many cases as possible, Staatic supports multiple external libraries.

• HTML5-PHP
  HTML5-PHP is a standards-compliant HTML5 parser and writer. It is stable and used in many production websites.
• PHP DOM Wrapper
  PHP DOM Wrapper is a simple but powerful DOM wrapper library to traverse and manipulate HTML documents.
• Simple Html Dom Parser
  Another popular HTML DOM parser. It leaves parts of the HTML that it does not manipulate as they are, which helps with HTML that is not well-formed and with HTML entities.

Since Staatic for WordPress v1.4.0, the default HTML DOM parser is PHP DOM Wrapper. Up to v1.3.4, the default (and only supported) parser was Simple Html Dom Parser.

According to our benchmarks, PHP DOM Wrapper performed better when processing large sites. If you are experiencing issues with the generated static HTML, you can try a different parser.

Note: if you are using Alpine.js shorthand syntax in your HTML, you will need to use Simple Html Dom Parser in order for the @event attributes to be retained.

Publication Task Timeout

This setting determines how long individual publication tasks may take before timing out and only applies to publications started from within WP-Admin. Publications started with WP-CLI do not use it and run without a per-task time limit, but they are still subject to the Publication Time Limit.

By default the Publication Task Timeout is set to 180 seconds.

Take the following into consideration when changing this value:

• If set too high, publications may fail due to web server timeouts (request timeout).
• If set too low, publications may fail due to long-running tasks timing out.

Note: only change this value to troubleshoot publication issues. Alternatively, use the WP-CLI Publish Command.

Staatic attempts to apply this value with PHP’s time limit handling. If a task that cannot resume is reached a second time after a timeout or a fatal error, the publication fails. The log entry names the task, points at the PHP error log for the cause, and suggests raising this setting when the task ran out of time.

Whether the deployment initiation step can resume depends on the selected deployment method. Staatic Cloud (Premium) resumes an interrupted initiation across background runs; the other deployment methods do not, and a second attempt at initiation fails the publication instead.

Publication Time Limit

This setting determines how many hours a publication may take in total before Staatic cancels it and marks it as failed. Unlike the Publication Task Timeout, it applies to publications started from WP-Admin as well as to publications started with WP-CLI.

By default the Publication Time Limit is set to 4 hours. Accepted values are whole numbers of hours between 1 and 72.

The limit is checked when each publication task starts, so a changed value takes effect at the next task rather than immediately.

Take the following into consideration when changing this value:

• Raise it for large sites where a complete publication genuinely needs more than four hours.
• A higher value also delays the moment a stuck publication is reported as failed.

If the entered value is empty or not a number, Staatic reports a settings error and restores the default of 4 hours. A value outside the accepted range is reported as a settings error and stored as the nearest accepted value.

Note: if the site defines a staatic_publication_timeout filter, it is applied after this setting and overrides it, without being held to the accepted range. See Publication lifecycle hooks.

Publish Changes

The Publish Changes function becomes available when modifications are made to public posts or related taxonomy records, enabling a partial publication instead of a full rebuild.

Publish Changes is based on tracked change events. It includes changed URLs, optionally related archive URLs for changed posts, and configured additional URLs. It is not a backlink scan of every page that links to the changed content.

Note: This functionality is part of Staatic Premium.

Update Archive Pages

By default Update Archive Pages is enabled. With this option enabled, linked taxonomy, author, and date archive pages associated with any modified posts and pages are updated as well.

Exclude Specific Taxonomies

By default Exclude Specific Taxonomies excludes the post_format taxonomy (“Formats”). Linked archive pages of the selected public taxonomies are not updated during the publication.

Include Taxonomy Pagination

By default Include Taxonomy Pagination is disabled. When enabled, paginated taxonomy archive pages related to changed content are included in the update process as well.

Exclude Author Archives

By default Exclude Author Archives is enabled. When enabled, linked author archive pages are not updated during the publication.

Include Author Pagination

By default Include Author Pagination is disabled. When enabled, paginated author archive pages related to changed content are included in the update process as well.

Exclude Date Archives

By default Exclude Date Archives is enabled. When enabled, linked date archive pages are not updated during the publication.

Include Date Pagination

By default Include Date Pagination is disabled. When enabled, paginated date archive pages related to changed content are included in the update process as well.

Pagination Limit

By default Pagination Limit is set to 5. This limits how many paginated archive pages are included when taxonomy, author, or date pagination is enabled for Publish Changes. If the saved value is empty or resolves to 0, Staatic falls back to 5.

Additional URLs

Specific URLs that are always processed when you use Publish Changes. Entries may be relative or absolute and are resolved against the publication entry URL. Invalid entries are skipped and reported as settings errors.

Examples of useful additional URLs:

• /
• /wp-sitemap.xml

Plugin Uninstall

These settings allow you to change which data is deleted when uninstalling the Staatic plugin. If you want to uninstall the plugin and do not plan to reinstall it later, you can enable all options below.

Both uninstall options are enabled by default.

Delete plugin settings

When enabled, the plugin’s registered settings and runtime options are deleted when you uninstall the plugin.

Delete plugin data

When enabled, the plugin’s database tables and migration version records are deleted when you uninstall the plugin.

Note: The Work Directory needs to be deleted manually at the moment.