Skip to main content
If a static site has a _redirects file in the repository’s root directory, Sevalla will parse the file’s contents and apply the custom redirect rules.

​
Redirect rule format and examples

Each redirect rule must be placed on its own line, with the original path followed by the new path or destination URL. Any line beginning with # will be treated as a comment and ignored. Paths are case-sensitive, and special characters must be URL-encoded. For example:
You can further customize redirect behavior by adding options at the end of each line, such as HTTP status codes, country rules, or language conditions.

​
HTTP status code example

Redirect permanently using a 301 status code:
Temporary redirect using a 302 status code:

​
Country rule example

Redirect visitors from France to a localized page:
Redirect visitors from the United States:

​
Language condition example

Redirect users who prefer Spanish based on the Accept-Language header:
Redirect users requesting German content:
Redirect rules are processed from top to bottom, and the first matching rule encountered is applied. If multiple rules target the same path, only the first one will be used, and all subsequent rules for that path will be ignored.

​
Header-based conditions

You can apply redirect rules when a request only contains a specific HTTP header by adding a Header: condition at the end of the rule. For example, the following rule redirects requests to the Markdown version of a page only when the client requests the text/markdown content type:
Header names are matched case-insensitively. This is useful for:
  • content negotiation,
  • API or client-specific redirects,
  • serving alternate formats,
  • or applying redirects only for certain request types.

​
Custom 404 page handling

You can create a custom 404 page for any path that doesn’t resolve to a static file; no redirect rules are required. Simply add a 404.html file to your site, and it will automatically be shown whenever a path cannot be found. You can also combine custom 404 pages with redirects by defining explicit rules for different languages or directory paths. For example:
These rules ensure that the corresponding 404 pages are displayed only for missing assets within those specific paths.

​
Force redirects

In some cases, a redirect may not occur because an existing file matches the requested URL path. To override this behavior, you can force the redirect by adding an exclamation mark (!) to the status code. For example:
In this example, /store/offers will always serve the content from /store/best-offers.html, even if a file such as /store/offers/index.html exists.

​
Splats

An asterisk (*) represents a splat, which matches anything that follows it in a path, for example:
This would redirect a URL such as /resources/guides/getting-started
to /library/guides/getting-started. Redirect rules always apply the first matching rule, therefore, more specific rules should appear before more general ones. The following limitations apply to splats:
  • **No mid-path wildcards: **You cannot place an asterisk in the middle of a path—for example, /docs/*.html is not valid. Splats can only appear at the end of a segment.
  • **No exclusions within a splat rule: **You cannot exclude specific paths directly within a splat redirect. To handle exceptions, create a more specific rule above the splat rule, ensuring it is matched first.

​
Domain-level redirects

Redirect rules can also match a full URL, including the hostname, instead of only a path. This is useful for redirecting one domain to another when both point to the same static site. For example, to permanently redirect the www subdomain to the apex domain:
This redirects any URL on www.example.com to the same path on example.com, for example, https://www.example.com/about redirects to https://example.com/about. The forced redirect (!) ensures the rule applies even when the requested file exists on the site. For the rule to take effect, both domains must be added and pointed to your static site.

​
Placeholders

You can use placeholders in both the origin and target paths to dynamically capture and reuse parts of a URL, for example:
In this example, a URL such as/store/electronics/headphoneswould redirect to /products/electronics/headphones. A placeholder matches either:
  • a single path segment between two slashes (/), or
  • the final segment of a path, including any file extension but excluding the query string.

​
Query parameters

You can use query parameters to create more precise redirect rules.

​
Matching a single query parameter

Example:
This redirects a URL like /search?q=laptops to /results/laptops with a 301 redirect. This rule matches only when the q parameter is present and no additional parameters are included. If the URL includes other parameters, such as &sort=asc, it will not match this rule.

​
Matching multiple query parameters

Add each parameter as its own key/value pair, separated by a space:
This matches URLs such as /products?category=shoes&brand=nike to /browse/shoes/nike

​
Handling optional or multiple parameter combinations

When parameters may or may not be present, list redirects from most specific to most general so the correct rule is matched first. Examples:
This pattern ensures all variations, both parameters, one parameter, or none, are handled correctly.

​
Single page applications (SPAs)

If your site is a single-page application, we strongly recommend adding a _redirects file to the root of your repository with the following rule:
This ensures that all routes, including deep links and client-side navigation, serve your index.html file with a 200 status, allowing your SPA’s router to handle the actual path logic.