Commit cc022a15 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis

Merge branch 'docs-pages-intro' into 'master'

Docs: Refactor Pages' intro guide

See merge request gitlab-org/gitlab-ce!27136
parents 4d39435e 4dfd4d27
No related merge requests found
...@@ -167,7 +167,7 @@ Here's a list of what you can't do with subgroups: ...@@ -167,7 +167,7 @@ Here's a list of what you can't do with subgroups:
- [GitLab Pages](../../project/pages/index.md) supports projects hosted under - [GitLab Pages](../../project/pages/index.md) supports projects hosted under
a subgroup, but not subgroup websites. a subgroup, but not subgroup websites.
That means that only the highest-level group supports That means that only the highest-level group supports
[group websites](../../project/pages/introduction.html#user-or-group-pages), [group websites](../../project/pages/getting_started_part_one.md#gitlab-pages-domain-names),
although you can have project websites under a subgroup. although you can have project websites under a subgroup.
- It is not possible to share a project with a group that's an ancestor of - It is not possible to share a project with a group that's an ancestor of
the group the project is in. That means you can only share as you walk down the group the project is in. That means you can only share as you walk down
......
--- ---
last_updated: 2018-02-16 last_updated: 2018-02-16
author: Marcia Ramos
author_gitlab: marcia
level: beginner
article_type: user guide
date: 2017-02-22
--- ---
# Static sites and GitLab Pages domains # Static sites and GitLab Pages domains
This document is the beginning of a comprehensive guide, made for those who want to On this docucument, learn how to name your project for GitLab Pages
publish a website with GitLab Pages but aren't familiar with according to your intended website's URL.
the entire process involved.
This [first document](#what-you-need-to-know-before-getting-started) of this series will present you to the concepts of
static sites, and go over how the default Pages domains work.
The [second document](getting_started_part_two.md) covers how to get started with GitLab Pages: deploy
a website from a forked project or create a new one from scratch.
The [third document](getting_started_part_three.md) will show you how to set up a custom domain or subdomain
to your site already deployed.
The [fourth document](getting_started_part_four.md) will show you how to create and tweak GitLab CI for
GitLab Pages.
To **enable** GitLab Pages for GitLab CE (Community Edition)
and GitLab EE (Enterprise Edition), please read the
[admin documentation](https://docs.gitlab.com/ce/administration/pages/index.html),
and/or watch this [video tutorial](https://youtu.be/dD8c7WNcc6s).
>**Note:**
For this guide, we assume you already have GitLab Pages
server up and running for your GitLab instance.
## What you need to know before getting started
Before we begin, let's understand a few concepts first.
## Static sites ## Static sites
...@@ -48,20 +17,10 @@ CSS, and JS, or use a [Static Site Generator (SSG)](https://www.staticgen.com/) ...@@ -48,20 +17,10 @@ CSS, and JS, or use a [Static Site Generator (SSG)](https://www.staticgen.com/)
to simplify your code and build the static site for you, to simplify your code and build the static site for you,
which is highly recommendable and much faster than hardcoding. which is highly recommendable and much faster than hardcoding.
### Further reading See the [further reading](#further-reading) section below for
references on static site concepts.
- Read through this technical overview on [Static versus Dynamic Websites](https://about.gitlab.com/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/)
- Understand [how modern Static Site Generators work](https://about.gitlab.com/2016/06/10/ssg-overview-gitlab-pages-part-2/) and what you can add to your static site
- You can use [any SSG with GitLab Pages](https://about.gitlab.com/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/)
- Fork an [example project](https://gitlab.com/pages) to build your website based upon
## GitLab Pages domain
If you set up a GitLab Pages project on GitLab.com, ## GitLab Pages domain names
it will automatically be accessible under a
[subdomain of `namespace.gitlab.io`](introduction.md#gitlab-pages-on-gitlabcom).
The `namespace` is defined by your username on GitLab.com,
or the group name you created this project under.
>**Note:** >**Note:**
If you use your own GitLab instance to deploy your If you use your own GitLab instance to deploy your
...@@ -70,11 +29,32 @@ Pages wildcard domain. This guide is valid for any GitLab instance, ...@@ -70,11 +29,32 @@ Pages wildcard domain. This guide is valid for any GitLab instance,
you just need to replace Pages wildcard domain on GitLab.com you just need to replace Pages wildcard domain on GitLab.com
(`*.gitlab.io`) with your own. (`*.gitlab.io`) with your own.
Learn more about [namespaces](../../group/index.md#namespaces). If you set up a GitLab Pages project on GitLab,
it will automatically be accessible under a
subdomain of `namespace.example.io`.
The [`namespace`](../../group/index.md#namespaces)
is defined by your username on GitLab.com,
or the group name you created this project under.
For GitLab self-managed instances, replace `example.io`
with your instance's Pages domain. For GitLab.com,
Pages domains are `*.gitlab.io`.
| Type of GitLab Pages | The name of the project created in GitLab | Website URL |
| -------------------- | ------------ | ----------- |
| User pages | `username.example.io` | `http(s)://username.example.io` |
| Group pages | `groupname.example.io` | `http(s)://groupname.example.io` |
| Project pages owned by a user | `projectname` | `http(s)://username.example.io/projectname` |
| Project pages owned by a group | `projectname` | `http(s)://groupname.example.io/projectname`|
| Project pages owned by a subgroup | `subgroup/projectname` | `http(s)://groupname.example.io/subgroup/projectname`|
CAUTION: **Warning:**
There are some known [limitations](introduction.md#limitations)
regarding namespaces served under the general domain name and HTTPS.
Make sure to read that section.
### Practical examples To understand Pages domains clearly, read the examples below.
#### Project Websites ### Project website examples
- You created a project called `blog` under your username `john`, - You created a project called `blog` under your username `john`,
therefore your project URL is `https://gitlab.com/john/blog/`. therefore your project URL is `https://gitlab.com/john/blog/`.
...@@ -92,7 +72,7 @@ Learn more about [namespaces](../../group/index.md#namespaces). ...@@ -92,7 +72,7 @@ Learn more about [namespaces](../../group/index.md#namespaces).
GitLab Pages for this project, the site will live under GitLab Pages for this project, the site will live under
`https://engineering.gitlab.io/docs/workflows`. `https://engineering.gitlab.io/docs/workflows`.
#### User and Group Websites ### User and Group website examples
- Under your username, `john`, you created a project called - Under your username, `john`, you created a project called
`john.gitlab.io`. Your project URL will be `https://gitlab.com/john/john.gitlab.io`. `john.gitlab.io`. Your project URL will be `https://gitlab.com/john/john.gitlab.io`.
...@@ -103,8 +83,6 @@ Learn more about [namespaces](../../group/index.md#namespaces). ...@@ -103,8 +83,6 @@ Learn more about [namespaces](../../group/index.md#namespaces).
Once you enable GitLab Pages for your project, Once you enable GitLab Pages for your project,
your website will be published under `https://websites.gitlab.io`. your website will be published under `https://websites.gitlab.io`.
> Support for subgroup project's websites was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/30548) in GitLab 11.8.
**General example:** **General example:**
- On GitLab.com, a project site will always be available under - On GitLab.com, a project site will always be available under
...@@ -115,3 +93,10 @@ Learn more about [namespaces](../../group/index.md#namespaces). ...@@ -115,3 +93,10 @@ Learn more about [namespaces](../../group/index.md#namespaces).
Pages server domain. Ask your sysadmin for this information. Pages server domain. Ask your sysadmin for this information.
_Read on about [Projects for GitLab Pages and URL structure](getting_started_part_two.md)._ _Read on about [Projects for GitLab Pages and URL structure](getting_started_part_two.md)._
### Further reading
- Read through this technical overview on [Static versus Dynamic Websites](https://about.gitlab.com/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/)
- Understand [how modern Static Site Generators work](https://about.gitlab.com/2016/06/10/ssg-overview-gitlab-pages-part-2/) and what you can add to your static site
- You can use [any SSG with GitLab Pages](https://about.gitlab.com/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/)
- Fork an [example project](https://gitlab.com/pages) to build your website based upon
\ No newline at end of file
...@@ -177,9 +177,6 @@ Note that [DNS propagation may take some time (up to 24h)](http://www.inmotionho ...@@ -177,9 +177,6 @@ Note that [DNS propagation may take some time (up to 24h)](http://www.inmotionho
although it's usually a matter of minutes to complete. Until it does, verification although it's usually a matter of minutes to complete. Until it does, verification
will fail and attempts to visit your domain will respond with a 404. will fail and attempts to visit your domain will respond with a 404.
Read through the [general documentation on GitLab Pages](introduction.md#add-a-custom-domain-to-your-pages-website) to learn more about adding
custom domains to GitLab Pages sites.
### Redirecting `www.domain.com` to `domain.com` with Cloudflare ### Redirecting `www.domain.com` to `domain.com` with Cloudflare
If you use Cloudflare, you can redirect `www` to `domain.com` without the need of adding both If you use Cloudflare, you can redirect `www` to `domain.com` without the need of adding both
......
...@@ -104,8 +104,8 @@ from the Pages group into a **user/group** website, you'll need to: ...@@ -104,8 +104,8 @@ from the Pages group into a **user/group** website, you'll need to:
### Create a project from scratch ### Create a project from scratch
1. From your **Project**'s **[Dashboard](https://gitlab.com/dashboard/projects)**, 1. From your **Project**'s **[Dashboard](https://gitlab.com/dashboard/projects)**,
click **New project**, and name it considering the click **New project**, and name it according to the
[practical examples](getting_started_part_one.md#practical-examples). [Pages domain names](getting_started_part_one.md#gitlab-pages-domain-names).
1. Clone it to your local computer, add your website 1. Clone it to your local computer, add your website
files to your project, add, commit and push to GitLab. files to your project, add, commit and push to GitLab.
1. From the your **Project**'s page, click **Set up CI/CD**: 1. From the your **Project**'s page, click **Set up CI/CD**:
......
doc/user/project/pages/img/pages_remove.png

3.69 KB

doc/user/project/pages/img/remove_pages.png

56.7 KB

...@@ -5,6 +5,11 @@ last_updated: 2019-03-05 ...@@ -5,6 +5,11 @@ last_updated: 2019-03-05
# GitLab Pages # GitLab Pages
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/80) in GitLab Enterprise Edition 8.3.
> - Custom CNAMEs with TLS support were [introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/173) in GitLab Enterprise Edition 8.5.
> - [Ported](https://gitlab.com/gitlab-org/gitlab-ce/issues/14605) to GitLab Community Edition in GitLab 8.17.
> Support for subgroup project's websites was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/30548) in GitLab 11.8.
**GitLab Pages is a feature that allows you to publish static websites **GitLab Pages is a feature that allows you to publish static websites
directly from a repository in GitLab.** directly from a repository in GitLab.**
...@@ -83,7 +88,7 @@ that will build your site and publish it to the GitLab Pages server. The sequenc ...@@ -83,7 +88,7 @@ that will build your site and publish it to the GitLab Pages server. The sequenc
scripts that GitLab CI/CD runs to accomplish this task is created from a file named scripts that GitLab CI/CD runs to accomplish this task is created from a file named
`.gitlab-ci.yml`, which you can [create and modify](getting_started_part_four.md) at will. `.gitlab-ci.yml`, which you can [create and modify](getting_started_part_four.md) at will.
You can either use GitLab's [default domain for GitLab Pages websites](getting_started_part_one.md#gitlab-pages-domain), You can either use GitLab's [default domain for GitLab Pages websites](getting_started_part_one.md#gitlab-pages-domain-names),
`*.gitlab.io`, or your own domain (`example.com`). In that case, you'll `*.gitlab.io`, or your own domain (`example.com`). In that case, you'll
need admin access to your domain's registrar (or control panel) to set it up with Pages. need admin access to your domain's registrar (or control panel) to set it up with Pages.
...@@ -128,7 +133,7 @@ To learn more about GitLab Pages, read the following tutorials: ...@@ -128,7 +133,7 @@ To learn more about GitLab Pages, read the following tutorials:
- [Projects for GitLab Pages and URL structure](getting_started_part_two.md): Forking projects and creating new ones from scratch, understanding URLs structure and baseurls - [Projects for GitLab Pages and URL structure](getting_started_part_two.md): Forking projects and creating new ones from scratch, understanding URLs structure and baseurls
- [GitLab Pages custom domains and SSL/TLS Certificates](getting_started_part_three.md): How to add custom domains and subdomains to your website, configure DNS records and SSL/TLS certificates - [GitLab Pages custom domains and SSL/TLS Certificates](getting_started_part_three.md): How to add custom domains and subdomains to your website, configure DNS records and SSL/TLS certificates
- [Creating and Tweaking GitLab CI/CD for GitLab Pages](getting_started_part_four.md): Understand how to create your own `.gitlab-ci.yml` for your site - [Creating and Tweaking GitLab CI/CD for GitLab Pages](getting_started_part_four.md): Understand how to create your own `.gitlab-ci.yml` for your site
- [Technical aspects, custom 404 pages, limitations](introduction.md) - [Exploring GitLab Pages](introduction.md): Technical aspects, specific configuration options, custom 404 pages, limitations
### GitLab Pages with Static Site Generators (SSGs) ### GitLab Pages with Static Site Generators (SSGs)
......
# Exploring GitLab Pages # Exploring GitLab Pages
> **Notes:** This document is a user guide to explore the options and settings
> GitLab Pages offers.
> - This feature was [introduced][ee-80] in GitLab EE 8.3.
> - Custom CNAMEs with TLS support were [introduced][ee-173] in GitLab EE 8.5.
> - GitLab Pages [was ported][ce-14605] to Community Edition in GitLab 8.17.
> - This document is about the user guide. To learn how to enable GitLab Pages
> across your GitLab instance, visit the [administrator documentation](../../../administration/pages/index.md).
With GitLab Pages you can host for free your static websites on GitLab. To familiarize yourself with GitLab Pages first:
Combined with the power of [GitLab CI] and the help of [GitLab Runner] you can
deploy static pages for your individual projects, your user or your group.
Read [GitLab Pages on GitLab.com](#gitlab-pages-on-gitlabcom) for specific - Read an [introduction to GitLab Pages](index.md#overview).
information, if you are using GitLab.com to host your website. - Learn [how to get started with Pages](index.md#getting-started).
- Learn how to enable GitLab Pages
across your GitLab instance on the [administrator documentation](../../../administration/pages/index.md).
## Getting started with GitLab Pages domains ## Pages requirements
> **Note:**
> In the rest of this document we will assume that the general domain name that
> is used for GitLab Pages is `example.io`.
In general there are two types of pages one might create:
- Pages per user (`username.example.io`) or per group (`groupname.example.io`)
- Pages per project (`username.example.io/projectname` or `groupname.example.io/projectname`)
In GitLab, usernames and groupnames are unique and we often refer to them
as [namespaces](../../group/index.md#namespaces). There can be only one namespace
in a GitLab instance. Below you
can see the connection between the type of GitLab Pages, what the project name
that is created on GitLab looks like and the website URL it will be ultimately
be served on.
| Type of GitLab Pages | The name of the project created in GitLab | Website URL |
| -------------------- | ------------ | ----------- |
| User pages | `username.example.io` | `http(s)://username.example.io` |
| Group pages | `groupname.example.io` | `http(s)://groupname.example.io` |
| Project pages owned by a user | `projectname` | `http(s)://username.example.io/projectname` |
| Project pages owned by a group | `projectname` | `http(s)://groupname.example.io/projectname`|
| Project pages owned by a subgroup | `subgroup/projectname` | `http(s)://groupname.example.io/subgroup/projectname`|
> **Warning:**
> There are some known [limitations](#limitations) regarding namespaces served
> under the general domain name and HTTPS. Make sure to read that section.
### GitLab Pages requirements
In brief, this is what you need to upload your website in GitLab Pages: In brief, this is what you need to upload your website in GitLab Pages:
1. Find out the general domain name that is used for GitLab Pages 1. Domain of the instance: domain name that is used for GitLab Pages
(ask your administrator). This is very important, so you should first make (ask your administrator).
sure you get that right. 1. GitLab CI/CD: a `.gitlab-ci.yml` file with a specific job named [`pages`][pages] in the root directory of your repository.
1. Create a project 1. A directory called `public` in your site's repo containing the content
1. Push a [`.gitlab-ci.yml` file][yaml] in the root directory to be published.
of your repository with a specific job named [`pages`][pages] 1. GitLab Runner enabled for the project.
1. Set up a GitLab Runner to build your website
> **Note:**
If [shared runners](../../../ci/runners/README.md) are enabled by your GitLab
administrator, you should be able to use them instead of bringing your own.
### User or group Pages
For user and group pages, the name of the project should be specific to the
username or groupname and the general domain name that is used for GitLab Pages.
Head over your GitLab instance that supports GitLab Pages and create a
repository named `username.example.io`, where `username` is your username on
GitLab. If the first part of the project name doesn't match exactly your
username, it won’t work, so make sure to get it right.
To create a group page, the steps are the same like when creating a website for
users. Just make sure that you are creating the project within the group's
namespace.
![Create a user-based pages project](img/pages_create_user_page.png)
---
After you push some static content to your repository and GitLab Runner uploads
the artifacts to GitLab CI, you will be able to access your website under
`http(s)://username.example.io`. Keep reading to find out how.
>**Note:**
If your username/groupname contains a dot, for example `foo.bar`, you will not
be able to use the wildcard domain HTTPS, read more at [limitations](#limitations).
### Project Pages ## GitLab Pages on GitLab.com
GitLab Pages for projects can be created by both user and group accounts.
The steps to create a project page for a user or a group are identical:
1. Create a new project
1. Push a [`.gitlab-ci.yml` file][yaml] in the root directory
of your repository with a specific job named [`pages`][pages].
1. Set up a GitLab Runner to build your website
A user's project will be served under `http(s)://username.example.io/projectname`
whereas a group's project under `http(s)://groupname.example.io/projectname`.
For practical examples for group and project Pages, read through the guide
[GitLab Pages from A to Z: Part 1 - Static sites and GitLab Pages domains](getting_started_part_one.md#practical-examples).
## Quick Start
Read through [GitLab Pages Quick Start Guide][pages-quick] or watch the video tutorial on
[how to publish a website with GitLab Pages on GitLab.com from a forked project][video-pages-fork].
See also [All you Need to Know About GitLab Pages][pages-index-guide] for a list with all the resources we have for GitLab Pages.
### Explore the contents of `.gitlab-ci.yml`
The key thing about GitLab Pages is the `.gitlab-ci.yml` file, something that
gives you absolute control over the build process. You can actually watch your
website being built live by following the CI job traces.
For a simplified user guide on setting up GitLab CI/CD for Pages, read through
the article [GitLab Pages from A to Z: Part 4 - Creating and Tweaking `.gitlab-ci.yml` for GitLab Pages](getting_started_part_four.md)
> **Note:**
> Before reading this section, make sure you familiarize yourself with GitLab CI
> and the specific syntax of[`.gitlab-ci.yml`][yaml] by
> following our [quick start guide].
To make use of GitLab Pages, the contents of `.gitlab-ci.yml` must follow the
rules below:
1. A special job named [`pages`][pages] must be defined
1. Any static content which will be served by GitLab Pages must be placed under
a `public/` directory
1. `artifacts` with a path to the `public/` directory must be defined
In its simplest form, `.gitlab-ci.yml` looks like: If you are using [GitLab Pages on GitLab.com](#gitlab-pages-on-gitlabcom) to host your website, then:
```yaml - The domain name for GitLab Pages on GitLab.com is `gitlab.io`.
pages: - Custom domains and TLS support are enabled.
script: - Shared runners are enabled by default, provided for free and can be used to
- my_commands build your website. If you want you can still bring your own Runner.
artifacts:
paths:
- public
```
When the Runner reaches to build the `pages` job, it executes whatever is ## Example projects
defined in the `script` parameter and if the job completes with a non-zero
exit status, it then uploads the `public/` directory to GitLab Pages.
The `public/` directory should contain all the static content of your website. Visit the [GitLab Pages group](https://gitlab.com/groups/pages) for a complete list of example projects. Contributions are very welcome.
Depending on how you plan to publish your website, the steps defined in the
[`script` parameter](../../../ci/yaml/README.md#script) may differ.
Be aware that Pages are by default branch/tag agnostic and their deployment ## Specific configuration options for Pages
relies solely on what you specify in `.gitlab-ci.yml`. If you don't limit the
`pages` job with the [`only` parameter](../../../ci/yaml/README.md#onlyexcept-basic),
whenever a new commit is pushed to whatever branch or tag, the Pages will be
overwritten. In the example below, we limit the Pages to be deployed whenever
a commit is pushed only on the `master` branch:
```yaml Learn how to set up GitLab CI/CD for specific use cases.
pages:
script:
- my_commands
artifacts:
paths:
- public
only:
- master
```
We then tell the Runner to treat the `public/` directory as `artifacts` and
upload it to GitLab. And since all these parameters were all under a `pages`
job, the contents of the `public` directory will be served by GitLab Pages.
#### How `.gitlab-ci.yml` looks like when the static content is in your repository ### `.gitlab-ci.yml` for plain HTML websites
Supposed your repository contained the following files: Supposed your repository contained the following files:
...@@ -201,55 +67,11 @@ pages: ...@@ -201,55 +67,11 @@ pages:
- master - master
``` ```
#### How `.gitlab-ci.yml` looks like when using a static generator ### `.gitlab-ci.yml` for a static site generator
In general, GitLab Pages support any kind of [static site generator][staticgen],
since `.gitlab-ci.yml` can be configured to run any possible command.
In the root directory of your Git repository, place the source files of your
favorite static generator. Then provide a `.gitlab-ci.yml` file which is
specific to your static generator.
The example below, uses [Jekyll] to build the static site: See this document for a [step-by-step guide](getting_started_part_four.md).
```yaml ### `.gitlab-ci.yml` for a repository where there's also actual code
image: ruby:2.1 # the script will run in Ruby 2.1 using the Docker image ruby:2.1
pages: # the build job must be named pages
script:
- gem install jekyll # we install jekyll
- jekyll build -d public/ # we tell jekyll to build the site for us
artifacts:
paths:
- public # this is where the site will live and the Runner uploads it in GitLab
only:
- master # this script is only affecting the master branch
```
Here, we used the Docker executor and in the first line we specified the base
image against which our jobs will run.
You have to make sure that the generated static files are ultimately placed
under the `public` directory, that's why in the `script` section we run the
`jekyll` command that jobs the website and puts all content in the `public/`
directory. Depending on the static generator of your choice, this command will
differ. Search in the documentation of the static generator you will use if
there is an option to explicitly set the output directory. If there is not
such an option, you can always add one more line under `script` to rename the
resulting directory in `public/`.
We then tell the Runner to treat the `public/` directory as `artifacts` and
upload it to GitLab.
---
See the [jekyll example project][pages-jekyll] to better understand how this
works.
For a list of Pages projects, see the [example projects](#example-projects) to
get you started.
#### How to set up GitLab Pages in a repository where there's also actual code
Remember that GitLab Pages are by default branch/tag agnostic and their Remember that GitLab Pages are by default branch/tag agnostic and their
deployment relies solely on what you specify in `.gitlab-ci.yml`. You can limit deployment relies solely on what you specify in `.gitlab-ci.yml`. You can limit
...@@ -294,28 +116,6 @@ also includes `.gitlab-ci.yml`. ...@@ -294,28 +116,6 @@ also includes `.gitlab-ci.yml`.
[jekyll-master]: https://gitlab.com/pages/jekyll-branched/tree/master [jekyll-master]: https://gitlab.com/pages/jekyll-branched/tree/master
[jekyll-pages]: https://gitlab.com/pages/jekyll-branched/tree/pages [jekyll-pages]: https://gitlab.com/pages/jekyll-branched/tree/pages
## Next steps
So you have successfully deployed your website, congratulations! Let's check
what more you can do with GitLab Pages.
### Example projects
Below is a list of example projects for GitLab Pages with a plain HTML website
or various static site generators. Contributions are very welcome.
- [Plain HTML](https://gitlab.com/pages/plain-html)
- [Jekyll](https://gitlab.com/pages/jekyll)
- [Hugo](https://gitlab.com/pages/hugo)
- [Middleman](https://gitlab.com/pages/middleman)
- [Hexo](https://gitlab.com/pages/hexo)
- [Brunch](https://gitlab.com/pages/brunch)
- [Metalsmith](https://gitlab.com/pages/metalsmith)
- [Harp](https://gitlab.com/pages/harp)
Visit the GitLab Pages group for a full list of example projects:
<https://gitlab.com/groups/pages>.
### Serving compressed assets ### Serving compressed assets
Most modern browsers support downloading files in a compressed format. This Most modern browsers support downloading files in a compressed format. This
...@@ -408,52 +208,6 @@ NOTE: **Note:** ...@@ -408,52 +208,6 @@ NOTE: **Note:**
When `public/data/index.html` exists, it takes priority over the `public/data.html` When `public/data/index.html` exists, it takes priority over the `public/data.html`
file for both the `/data` and `/data/` URL paths. file for both the `/data` and `/data/` URL paths.
### Add a custom domain to your Pages website
For a complete guide on Pages domains, read through the article
[GitLab Pages from A to Z: Part 3 - GitLab Pages custom domains and SSL/TLS Certificates](getting_started_part_three.md)
If this setting is enabled by your GitLab administrator, you should be able to
see the **New Domain** button when visiting your project's settings through the
gear icon in the top right and then navigating to **Pages**.
![New domain button](img/pages_new_domain_button.png)
---
You can add multiple domains pointing to your website hosted under GitLab.
Once the domain is added, you can see it listed under the **Domains** section.
![Pages multiple domains](img/pages_multiple_domains.png)
---
As a last step, you need to configure your DNS and add a CNAME pointing to your
user/group page. Click on the **Details** button of a domain for further
instructions.
![Pages DNS details](img/pages_dns_details.png)
---
>**Note:**
Currently there is support only for custom domains on per-project basis. That
means that if you add a custom domain (`example.com`) for your user website
(`username.example.io`), a project that is served under `username.example.io/foo`,
will not be accessible under `example.com/foo`.
### Secure your custom domain website with TLS
When you add a new custom domain, you also have the chance to add a TLS
certificate. If this setting is enabled by your GitLab administrator, you
should be able to see the option to upload the public certificate and the
private key when adding a new domain.
![Pages upload cert](img/pages_upload_cert.png)
For a complete guide on Pages domains, read through the article
[GitLab Pages from A to Z: Part 3 - GitLab Pages custom domains and SSL/TLS Certificates](getting_started_part_three.md)
### Custom error codes pages ### Custom error codes pages
You can provide your own 403 and 404 error pages by creating the `403.html` and You can provide your own 403 and 404 error pages by creating the `403.html` and
...@@ -472,29 +226,17 @@ If the case of `404.html`, there are different scenarios. For example: ...@@ -472,29 +226,17 @@ If the case of `404.html`, there are different scenarios. For example:
- If you use a custom domain and try to access `/non/existing_file`, GitLab - If you use a custom domain and try to access `/non/existing_file`, GitLab
Pages will try to serve only `/404.html`. Pages will try to serve only `/404.html`.
### Remove the contents of your pages ### Redirects in GitLab Pages
If you ever feel the need to purge your Pages content, you can do so by going
to your project's settings through the gear icon in the top right, and then
navigating to **Pages**. Hit the **Remove pages** button and your Pages website
will be deleted. Simple as that.
![Remove pages](img/pages_remove.png)
## GitLab Pages on GitLab.com
If you are using GitLab.com to host your website, then:
- The general domain name for GitLab Pages on GitLab.com is `gitlab.io`.
- Custom domains and TLS support are enabled.
- Shared runners are enabled by default, provided for free and can be used to
build your website. If you want you can still bring your own Runner.
The rest of the guide still applies. Since you cannot use any custom server configuration files, like `.htaccess` or
any `.conf` file, if you want to redirect a page to another
location, you can use the [HTTP meta refresh tag][metarefresh].
See also: [GitLab Pages from A to Z: Part 1 - Static sites and GitLab Pages domains](getting_started_part_one.md#gitlab-pages-domain). Some static site generators provide plugins for that functionality so that you
don't have to create and edit HTML files manually. For example, Jekyll has the
[redirect-from plugin](https://github.com/jekyll/jekyll-redirect-from).
## GitLab Pages access control **[CORE ONLY]** ### GitLab Pages Access Control **[CORE ONLY]**
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/33422) in GitLab 11.5. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/33422) in GitLab 11.5.
...@@ -536,6 +278,15 @@ The next time someone tries to access your website and the access control is ...@@ -536,6 +278,15 @@ The next time someone tries to access your website and the access control is
enabled, they will be presented with a page to sign into GitLab and verify they enabled, they will be presented with a page to sign into GitLab and verify they
can access the website. can access the website.
## Unpublishing your Pages
If you ever feel the need to purge your Pages content, you can do so by going
to your project's settings through the gear icon in the top right, and then
navigating to **Pages**. Hit the **Remove pages** button and your Pages website
will be deleted.
![Remove pages](img/remove_pages.png)
## Limitations ## Limitations
When using Pages under the general domain of a GitLab instance (`*.example.io`), When using Pages under the general domain of a GitLab instance (`*.example.io`),
...@@ -550,16 +301,6 @@ don't redirect HTTP to HTTPS. ...@@ -550,16 +301,6 @@ don't redirect HTTP to HTTPS.
GitLab Pages [does **not** support group websites for subgroups](../../group/subgroups/index.md#limitations). GitLab Pages [does **not** support group websites for subgroups](../../group/subgroups/index.md#limitations).
You can only create the highest-level group website. You can only create the highest-level group website.
## Redirects in GitLab Pages
Since you cannot use any custom server configuration files, like `.htaccess` or
any `.conf` file, if you want to redirect a page to another
location, you can use the [HTTP meta refresh tag][metarefresh].
Some static site generators provide plugins for that functionality so that you
don't have to create and edit HTML files manually. For example, Jekyll has the
[redirect-from plugin](https://github.com/jekyll/jekyll-redirect-from).
## Frequently Asked Questions ## Frequently Asked Questions
### Can I download my generated pages? ### Can I download my generated pages?
...@@ -581,8 +322,6 @@ No, you don't. You can create your project first and it will be accessed under ...@@ -581,8 +322,6 @@ No, you don't. You can create your project first and it will be accessed under
For a list of known issues, visit GitLab's [public issue tracker]. For a list of known issues, visit GitLab's [public issue tracker].
[jekyll]: http://jekyllrb.com/ [jekyll]: http://jekyllrb.com/
[ee-80]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/80
[ee-173]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/173
[pages-daemon]: https://gitlab.com/gitlab-org/gitlab-pages [pages-daemon]: https://gitlab.com/gitlab-org/gitlab-pages
[gitlab ci]: https://about.gitlab.com/gitlab-ci [gitlab ci]: https://about.gitlab.com/gitlab-ci
[gitlab runner]: https://docs.gitlab.com/runner/ [gitlab runner]: https://docs.gitlab.com/runner/
...@@ -592,7 +331,6 @@ For a list of known issues, visit GitLab's [public issue tracker]. ...@@ -592,7 +331,6 @@ For a list of known issues, visit GitLab's [public issue tracker].
[pages-jekyll]: https://gitlab.com/pages/jekyll [pages-jekyll]: https://gitlab.com/pages/jekyll
[metarefresh]: https://en.wikipedia.org/wiki/Meta_refresh [metarefresh]: https://en.wikipedia.org/wiki/Meta_refresh
[public issue tracker]: https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name=pages [public issue tracker]: https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name=pages
[ce-14605]: https://gitlab.com/gitlab-org/gitlab-ce/issues/14605
[quick start guide]: ../../../ci/quick_start/README.md [quick start guide]: ../../../ci/quick_start/README.md
[pages-index-guide]: index.md [pages-index-guide]: index.md
[pages-quick]: getting_started_part_one.md [pages-quick]: getting_started_part_one.md
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment