Merge branch 'docs-crosslink-pages-guides' into 'master'

Docs: crosslink Pages guides

Closes #38427

See merge request gitlab-org/gitlab-ce!14542

3 files changed, 64 insertions, 4 deletions

diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md
index 46fa4378fe7..453e10184f0 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.md#namespaces).
+
 ### Practical examples
 
 #### Project Websites
diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md
index 53fd1786cfa..0096f8507d2 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.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
+> **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)
@@ -16,6 +21,21 @@ 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`.
 
+### 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:
+
+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
+
+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 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
 
 A Domain Name System (DNS) web service routes visitors to websites
@@ -99,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
diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md
index 9ecf7a3a8e7..4fcdfa7b281 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.md#gitlab-pages-domain).
+
 ## Limitations
 
 When using Pages under the general domain of a GitLab instance (`*.example.io`),