From 3995916596dff76ecb72aa8bda5e9d04b728fd00 Mon Sep 17 00:00:00 2001 From: Marcia Ramos Date: Wed, 27 Sep 2017 18:53:15 -0300 Subject: [PATCH 1/8] cross-link Pages references --- doc/user/project/pages/introduction.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 9ecf7a3a8e7..63930fb3bf7 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -28,7 +28,8 @@ In general there are two types of pages one might create: - 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. There can be only one namespace in a GitLab instance. Below you +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. @@ -98,6 +99,9 @@ The steps to create a project page for a user or a group are identical: 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 @@ -111,6 +115,9 @@ 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#creating-and-tweaking-gitlab-ci-yml-for-gitlab-pages) + > **Note:** > Before reading this section, make sure you familiarize yourself with GitLab CI > and the specific syntax of[`.gitlab-ci.yml`][yaml] by @@ -311,6 +318,9 @@ Visit the GitLab Pages group for a full list of example projects: ### 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 - Setting Up Custom Domains - DNS Records and SSL/TLS Certificates](getting_started_part_three.md#setting-up-custom-domains-dns-records-and-ssl-tls-certificates) + 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**. @@ -349,6 +359,9 @@ 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 - Setting Up Custom Domains - DNS Records and SSL/TLS Certificates](getting_started_part_three.md#setting-up-custom-domains-dns-records-and-ssl-tls-certificates) + ### Custom error codes pages You can provide your own 403 and 404 error pages by creating the `403.html` and @@ -387,6 +400,8 @@ If you are using GitLab.com to host your website, then: The rest of the guide still applies. +See also: [GitLab Pages from A to Z: Part 1 - Static sites and GitLab Pages domains](getting_started_part_one.html#gitlab-pages-domain). + ## Limitations When using Pages under the general domain of a GitLab instance (`*.example.io`), From c82ce3b16dc77d96969f23132fe7f9d8534367b6 Mon Sep 17 00:00:00 2001 From: Marcia Ramos Date: Wed, 27 Sep 2017 18:53:22 -0300 Subject: [PATCH 2/8] update links --- doc/user/project/pages/getting_started_part_one.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 46fa4378fe7..3d62bfe5fef 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -62,7 +62,7 @@ which is highly recommendable and much faster than hardcoding. If you set up a GitLab Pages project on GitLab.com, it will automatically be accessible under a -[subdomain of `namespace.pages.io`](https://docs.gitlab.com/ce/user/project/pages/). +[subdomain of `namespace.pages.io`](introduction.md#gitlab-pages-on-gitlab-com). The `namespace` is defined by your username on GitLab.com, or the group name you created this project under. @@ -73,6 +73,8 @@ Pages wildcard domain. This guide is valid for any GitLab instance, you just need to replace Pages wildcard domain on GitLab.com (`*.gitlab.io`) with your own. +Learn more about [namespaces](../../group/index.html#namespaces). + ### Practical examples #### Project Websites From 3235ecb7c70a925023107bc6796f24cdecf6f790 Mon Sep 17 00:00:00 2001 From: Marcia Ramos Date: Wed, 27 Sep 2017 19:08:11 -0300 Subject: [PATCH 3/8] add intro section "Custom domains for GitLab Pages" for comprehensiveness and SEO --- .../project/pages/getting_started_part_three.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md index 53fd1786cfa..cb9ef897433 100644 --- a/doc/user/project/pages/getting_started_part_three.md +++ b/doc/user/project/pages/getting_started_part_three.md @@ -16,6 +16,19 @@ As described in the previous part of this series, setting up GitLab Pages with c These steps assume you've already [set your site up](getting_started_part_two.md) and and it's served under the default Pages domain `namespace.gitlab.io`, or `namespace.gitlab.io/project-name`. +### Custom domains for GitLab Pages + +To use one or more custom domain with your Pages site, there are two things +you should consider first, which we'll cover in this guide: + +1. Either if you're adding a **root domain** or a **subdomain**, for which +you'll need to set up [DNS records](#dns-records) +1. Whether you want to add an [SSL/TLS certificate](#ssl-tls-certificates) or not + +Let's start from the beginning. If you already know how these things work +and want to skip the tutorial, you may be interested in the [TL;DR](#tl-dr) section +below. + ### DNS Records A Domain Name System (DNS) web service routes visitors to websites From ac4ddda5c96d167aed493748e272291ca6bd9911 Mon Sep 17 00:00:00 2001 From: Marcia Ramos Date: Wed, 27 Sep 2017 19:12:55 -0300 Subject: [PATCH 4/8] fixes links (html => md) --- doc/user/project/pages/getting_started_part_one.md | 2 +- doc/user/project/pages/getting_started_part_three.md | 2 +- doc/user/project/pages/introduction.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 3d62bfe5fef..453e10184f0 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -73,7 +73,7 @@ Pages wildcard domain. This guide is valid for any GitLab instance, you just need to replace Pages wildcard domain on GitLab.com (`*.gitlab.io`) with your own. -Learn more about [namespaces](../../group/index.html#namespaces). +Learn more about [namespaces](../../group/index.md#namespaces). ### Practical examples diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md index cb9ef897433..8466e563965 100644 --- a/doc/user/project/pages/getting_started_part_three.md +++ b/doc/user/project/pages/getting_started_part_three.md @@ -1,6 +1,6 @@ # GitLab Pages from A to Z: Part 3 -> **Article [Type](../../../development/writing_documentation.html#types-of-technical-articles)**: user guide || +> **[Article Type](../../../development/writing_documentation.md#types-of-technical-articles)**: user guide || > **Level**: beginner || > **Author**: [Marcia Ramos](https://gitlab.com/marcia) || > **Publication date:** 2017/02/22 diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 63930fb3bf7..4fcdfa7b281 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -400,7 +400,7 @@ If you are using GitLab.com to host your website, then: The rest of the guide still applies. -See also: [GitLab Pages from A to Z: Part 1 - Static sites and GitLab Pages domains](getting_started_part_one.html#gitlab-pages-domain). +See also: [GitLab Pages from A to Z: Part 1 - Static sites and GitLab Pages domains](getting_started_part_one.md#gitlab-pages-domain). ## Limitations From e59042a3ede135356270bd2f427b9b7f355ee164 Mon Sep 17 00:00:00 2001 From: Marcia Ramos Date: Thu, 28 Sep 2017 13:36:24 -0300 Subject: [PATCH 5/8] add section "Add your custom domain to GitLab Pages settings" --- .../pages/getting_started_part_three.md | 28 ++++++++++++++++--- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md index 8466e563965..7f24b25cfd3 100644 --- a/doc/user/project/pages/getting_started_part_three.md +++ b/doc/user/project/pages/getting_started_part_three.md @@ -16,7 +16,7 @@ As described in the previous part of this series, setting up GitLab Pages with c These steps assume you've already [set your site up](getting_started_part_two.md) and and it's served under the default Pages domain `namespace.gitlab.io`, or `namespace.gitlab.io/project-name`. -### Custom domains for GitLab Pages +### Adding your custom domain to GitLab Pages To use one or more custom domain with your Pages site, there are two things you should consider first, which we'll cover in this guide: @@ -25,9 +25,11 @@ you should consider first, which we'll cover in this guide: you'll need to set up [DNS records](#dns-records) 1. Whether you want to add an [SSL/TLS certificate](#ssl-tls-certificates) or not -Let's start from the beginning. If you already know how these things work -and want to skip the tutorial, you may be interested in the [TL;DR](#tl-dr) section -below. +To finish the association, you need to [add your domain to your project's Pages settings](#add-your-custom-domain-to-gitlab-pages-settings). + +Let's start from the beginning with [DNS records](#dns-records). +If you already know how these things work and want to skip the tutorial, +you may be interested in the [TL;DR](#tl-dr) section below. ### DNS Records @@ -96,6 +98,24 @@ without any `/project-name`. ![DNS CNAME record pointing to GitLab.com project](img/dns_cname_record_example.png) +#### Add your custom domain to GitLab Pages settings + +Once you've set the DNS record, you'll need navigate to your project's +**Setting > Pages** and click **+ New domain** to add your custom domain to +GitLab Pages. You can choose whether to add an [SSL/TLS certificate](#ssl-tls-certificates) +to make your website accessible under HTTPS or leave it blank. If don't add a certificate, +your site will be accessible only via HTTP: + +![Add new domain](img/add_certificate_to_pages.png) + +You add more than one alias (custom domains and subdomains) to the same project. +An alias can be understood as a way to have many doors leading to the same room. + +All the aliases you've set to your site will be listed on **Setting > Pages**. +From that page, you can view, add, and remove them. + +Read through the [general documentation on GitLab Pages](introduction.md#add-a-custom-domain-to-your-pages-website) to learn more. + #### TL;DR | From | DNS Record | To | From 77ec130e33492773756e5ed1e495fc4d531d4919 Mon Sep 17 00:00:00 2001 From: Marcia Ramos Date: Thu, 28 Sep 2017 13:41:53 -0300 Subject: [PATCH 6/8] add note on DNS propagation time --- doc/user/project/pages/getting_started_part_three.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md index 7f24b25cfd3..24a7b497daf 100644 --- a/doc/user/project/pages/getting_started_part_three.md +++ b/doc/user/project/pages/getting_started_part_three.md @@ -114,6 +114,10 @@ An alias can be understood as a way to have many doors leading to the same room. All the aliases you've set to your site will be listed on **Setting > Pages**. From that page, you can view, add, and remove them. +Note that [DNS propagation may take some time (up to 24h)](http://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/domain-names-dns-changes), +although it's usually a matter of minutes to complete. Until it does, visits +to your domain address 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. #### TL;DR From aa21f0935382b81beb6115c82da3a3573f93cf18 Mon Sep 17 00:00:00 2001 From: Marcia Ramos Date: Thu, 28 Sep 2017 13:49:34 -0300 Subject: [PATCH 7/8] copyedit + last_updated --- .../project/pages/getting_started_part_three.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md index 24a7b497daf..4fc6f701144 100644 --- a/doc/user/project/pages/getting_started_part_three.md +++ b/doc/user/project/pages/getting_started_part_three.md @@ -1,9 +1,14 @@ +--- +last_updated: 2017-09-28 +--- + # GitLab Pages from A to Z: Part 3 > **[Article Type](../../../development/writing_documentation.md#types-of-technical-articles)**: user guide || > **Level**: beginner || > **Author**: [Marcia Ramos](https://gitlab.com/marcia) || -> **Publication date:** 2017/02/22 +> **Publication date:** 2017-02-22 || +> **Last updated**: 2017-09-28 - [Part 1: Static sites and GitLab Pages domains](getting_started_part_one.md) - [Part 2: Quick start guide - Setting up GitLab Pages](getting_started_part_two.md) @@ -115,10 +120,11 @@ All the aliases you've set to your site will be listed on **Setting > Pages**. From that page, you can view, add, and remove them. Note that [DNS propagation may take some time (up to 24h)](http://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/domain-names-dns-changes), -although it's usually a matter of minutes to complete. Until it does, visits -to your domain address will respond with a 404. +although it's usually a matter of minutes to complete. Until it does, visit attempts +to 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. +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. #### TL;DR From 98f4c8cb5bdedadfa3517862934a4bf65dfeea41 Mon Sep 17 00:00:00 2001 From: Marcia Ramos Date: Thu, 28 Sep 2017 14:00:20 -0300 Subject: [PATCH 8/8] copyedit - reorg headers --- .../pages/getting_started_part_three.md | 50 +++++++++---------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md index 4fc6f701144..0096f8507d2 100644 --- a/doc/user/project/pages/getting_started_part_three.md +++ b/doc/user/project/pages/getting_started_part_three.md @@ -33,8 +33,8 @@ you'll need to set up [DNS records](#dns-records) To finish the association, you need to [add your domain to your project's Pages settings](#add-your-custom-domain-to-gitlab-pages-settings). Let's start from the beginning with [DNS records](#dns-records). -If you already know how these things work and want to skip the tutorial, -you may be interested in the [TL;DR](#tl-dr) section below. +If you already know how they work and want to skip the introduction to DNS, +you may be interested in skipping it until the [TL;DR](#tl-dr) section below. ### DNS Records @@ -103,29 +103,6 @@ without any `/project-name`. ![DNS CNAME record pointing to GitLab.com project](img/dns_cname_record_example.png) -#### Add your custom domain to GitLab Pages settings - -Once you've set the DNS record, you'll need navigate to your project's -**Setting > Pages** and click **+ New domain** to add your custom domain to -GitLab Pages. You can choose whether to add an [SSL/TLS certificate](#ssl-tls-certificates) -to make your website accessible under HTTPS or leave it blank. If don't add a certificate, -your site will be accessible only via HTTP: - -![Add new domain](img/add_certificate_to_pages.png) - -You add more than one alias (custom domains and subdomains) to the same project. -An alias can be understood as a way to have many doors leading to the same room. - -All the aliases you've set to your site will be listed on **Setting > Pages**. -From that page, you can view, add, and remove them. - -Note that [DNS propagation may take some time (up to 24h)](http://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/domain-names-dns-changes), -although it's usually a matter of minutes to complete. Until it does, visit attempts -to 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. - #### TL;DR | From | DNS Record | To | @@ -142,6 +119,29 @@ domain. E.g., **do not** point your `subdomain.domain.com` to `namespace.gitlab.io.` or `namespace.gitlab.io/`. > - GitLab Pages IP on GitLab.com [has been changed](https://about.gitlab.com/2017/03/06/we-are-changing-the-ip-of-gitlab-pages-on-gitlab-com/) from `104.208.235.32` to `52.167.214.135`. +### Add your custom domain to GitLab Pages settings + +Once you've set the DNS record, you'll need navigate to your project's +**Setting > Pages** and click **+ New domain** to add your custom domain to +GitLab Pages. You can choose whether to add an [SSL/TLS certificate](#ssl-tls-certificates) +to make your website accessible under HTTPS or leave it blank. If don't add a certificate, +your site will be accessible only via HTTP: + +![Add new domain](img/add_certificate_to_pages.png) + +You can add more than one alias (custom domains and subdomains) to the same project. +An alias can be understood as having many doors leading to the same room. + +All the aliases you've set to your site will be listed on **Setting > Pages**. +From that page, you can view, add, and remove them. + +Note that [DNS propagation may take some time (up to 24h)](http://www.inmotionhosting.com/support/domain-names/dns-nameserver-changes/domain-names-dns-changes), +although it's usually a matter of minutes to complete. Until it does, visit attempts +to 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. + ### SSL/TLS Certificates Every GitLab Pages project on GitLab.com will be available under