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: 
# Redirects
/shop                 /store
/products/item.php    /products/item
/events               /community/events
/old-dashboard        https://example.com/new-dashboard
/team/john%smith%1    /team/about-john%smith%1
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. 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.

​
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: 
/en/* /en/404.html 404
/de/* /de/404.html 404
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: 
/store/offers  /store/best-offers.html 200!
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: 
/resources/*   /library/:splat
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.

​
Placeholders

You can use placeholders in both the origin and target paths to dynamically capture and reuse parts of a URL, for example: 
/store/:category/:item   /products/:category/:item
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: 
/search q=:term   /results/:term   301
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: 
/products category=:category brand=:brand   /browse/:category/:brand   301
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: 
# Both parameters present (order from the browser does not matter)
/items/* color=:color size=:size   /catalog/:color/:size/:splat   301

# Only one parameter present (must match exactly)
/items/* color=:color              /catalog/:color/:splat         301
/items/* size=:size                /catalog/:size/:splat          301

# Base rule when no parameters match
# If this is the only rule, all query parameters are forwarded automatically.
/items/*                           /catalog/:splat                301
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: 
/*   /index.html   200
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.