Redirects and rewrites

You can add redirects to your site e.g. if you have changed the structure of your site but want to keep old links working (as you should). Just add a _redirects file with your redirects to the root of your public folder. The file should list one redirect per line: first the URL that should be redirected, followed by any whitespace, followed by the URL to redirect to. The URL to redirect to can be an absolute URL leading to another domain.

Actual static files are always matched first - redirects and rewrites are only considered if no static file is found. You can change this behavior by forcing redircets to take place - see below.

Example _redirects file:

/alternative/page/   /primary/page/
/my/old/post.html    /posts/old/    301
/de/*                /de/404.html   404
/hosting/            https://www.statichost.eu

Specifying the status code

Optionally, you can specify the HTTP status code used for the redirect after the redirect specification. By default, the redirect is a temporary redirect (technically a 302 Found HTTP status code). A common redirect status code you might want to use is 301, which represents a permanent redirect.

Allowed redirect status codes are:

301 Moved Permanently
302 Found
303 See Other
307 Temporary Redirect
308 Permanent Redirect

Allowed rewrite status codes are (see below for details):

200 Ok
404 Not Found
410 Gone

Custom 404 Not Found pages

Because static files are matched first, you can specify subdirectory-specific 404 pages with a wildcard and a 404 rewrite. This way, you can have e.g. language-specific 404 pages, assuming that pages are organized into subdirectories by language. In the example below, the last global 404 page is strictly not needed (the /404.html page is used by default if it exists), but is added for clarity.

/de/*  /de/404.html   404
/it/*  /it/404.html   404
/*     /404.html      404

Rewrites and proxying

It is also possible to rewrite or proxy a request to either a page on the site itself (e.g., for SPA applications) or to a URL on a completely different service (e.g., for proxying API requests). To utilize this feature, simply set the HTTP status code to 200 at the end of your rule. This indicates that the incoming request should be served from the target URL instead.

Example of a rewrite:

/*    /index.html    200

In this example, all requests will be internally rewritten to the index page. This is how you’d like a client-side Single Page Application (SPA) to work.

Wildcard matching

You can use a wildcard asterisk at the end of your “from” URL. This allows you to specify a pattern that can match multiple routes. The matched portion can be included in the “to” part using :splat.

Example with wildcard:

/blog/*    /posts/:splat    301

In this case, a request to /blog/my-post would redirect to /posts/my-post, effectively maintaining the dynamic nature of the URL.

Forcing redirects

Normally, existing static files are always served before applying any redirects. If you are absolutely sure that you want to redirect (or proxy) even though a static file exists, you can “force” the redirect to always be applied. To do this, add an exclamation mark after the status code you want to use:

/archive/*    https://archive.example.org/:splat    301!