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
> - [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