Customize GitLab Pages for a project
Description
Projects sometimes need to customize how GitLab Pages, for example for redirects or custom headers, but they don't have access to the Pages webserver. Heroku Static Buildpack gives a good example of how a project could configure various features (in this case of nginx).
Proposal
If pages.json
or pages.yaml
is present in the root folder of the pages artifacts bundle, process for things like:
Default Character Set
This allows you to specify a character set for your text assets (HTML, Javascript, CSS, and so on). For most apps, this should be the default value of "UTF-8", but you can override it by setting encoding
:
{
"encoding": "US-ASCII"
}
Clean URLs
For SEO purposes, you can drop the .html extension from URLs for say a blog site. This means users could go to /foo instead of /foo.html.
{
"clean_urls": true
}
By default this is set to false
.
Custom Routes
You can define custom routes that combine to a single file. This allows you to preserve routing for a single page web application. The following operators are supported:
-
*
supports a single path segment in the URL. In the configuration below,/baz.html
would match but/bar/baz.html
would not. -
**
supports any length in the URL. In the configuration below, both/route/foo
would work and/route/foo/bar/baz
.
{
"routes": {
"/*.html": "index.html",
"/route/**": "bar/baz.html"
}
}
Custom Redirects
With custom redirects, you can move pages to new routes but still preserve the old routes for SEO purposes. By default, we return a 301
status code, but you can specify the status code you want.
{
"redirects": {
"/old/gone/": {
"url": "/",
"status": 302
}
}
}
etc.
Links / references
Documentation blurb
(Write the start of the documentation of this feature here, include:
- Why should someone use it; what's the underlying problem.
- What is the solution.
- How does someone use this
During implementation, this can then be copied and used as a starter for the documentation.)