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
pages.gay has its own config file, .pages.json
, placed at the root of a repository.
allowPrivate
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
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
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 username.pages.gay/exciting-project
to redirect to username.pages.gay/blog/my-new-project
, 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 user.pages.gay/repo
would match user.pages.gay/repo/exciting-project
.
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
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