Advanced usage

Custom 404 pages

To customise the 404 page of a site, make a file at 404.html or 404/index.html.

.pages.json has its own config file, .pages.json, placed at the root of a repository.


If your repository is private, but you’d like the page to be public anyways, you’ll need to set a .pages.json property to allow it. This is to make sure you know that you’re allowing the site to be public.

	"allowPrivate": true


basePath is used for specifying where the base of the repository is. For example, if your website needs to be compiled, and the root of the repository contains the source code, you can compile your site as static HTML in a built directory in your repository and set basePath to built with the following .pages.json file:

	"basePath": "built"


allowInsecure enables HTTP support. If false or unspecified, requests redirect to HTTPS instead of HTTP.

_redirects file

_redirects files allow for, as the name implies, creating redirects on your website. For example, if you want to redirect to, you can setup a redirect with the following _redirects file.

/exciting-project    /blog/my-new-project

Destinations are relative to the root of the repository, so the above _redirects file if hosted on would match

HTTP status codes

By default, these redirects use the HTTP status code 301, but this can be customised by setting an HTTP status code after the destination.

/exciting-project    /blog/my-new-project      302

If a status code other than 301 or 302 is used, instead of actually redirecting the user to a new URL the content from the destination file will be sent to the user.

Any of the following HTTP status codes are supported:

  • 200 - OK.
  • 301 - Permanent redirect (the default status).
  • 302 - Found (commonly used for temporary redirects).
  • 404 - Not found.
  • 410 - Gone (the requested content has been permanently removed).
  • 451 - Unavailable for legal reasons.

Path parameters

_redirects can be much more complicated, though. If you’d like to redirect any path that matches a certain format, you can use parameters by putting a colon : character before the name of the parameter. You can then use the parameters in the destination path. The parameters can be in any order.

/article/:month/:day/:year/:title    /post/:year/:month/:day/:title


Wildcards are also supported, and you can “splat” the wildcard onto the destination:

/some-old-page/*    /some-new-page/:splat

Using a wildcard and the HTTP status code 200, hosting an SPA (Single Page App) is possible by redirecting all URLs to the HTML file of the SPA. With the following setup, the index.html file will be used for /any-path-at-all.

/*    /index.html    200