Merge branch 'docs-pages-refactor-article-series' into 'master'

Docs: Pages - clean up articles

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

6 files changed, 53 insertions, 97 deletions

diff --git a/doc/development/writing_documentation.md b/doc/development/writing_documentation.md
index 700039392ef..403c9d08752 100644
--- a/doc/development/writing_documentation.md
+++ b/doc/development/writing_documentation.md
@@ -240,7 +240,7 @@ Suppose there's a process to go from point A to point B in 5 steps: `(A) 1 > 2 >
 
 A **guide** can be understood as a description of certain processes to achieve a particular objective. A guide brings you from A to B describing the characteristics of that process, but not necessarily going over each step. It can mention, for example, steps 2 and 3, but does not necessarily explain how to accomplish them.
 
-- Live example: "GitLab Pages from A to Z - [Part 1](../user/project/pages/getting_started_part_one.md) to [Part 4](../user/project/pages/getting_started_part_four.md)"
+- Live example: "[Static sites and GitLab Pages domains (Part 1)](../user/project/pages/getting_started_part_one.md) to [Creating and Tweaking GitLab CI/CD for GitLab Pages (Part 4)](../user/project/pages/getting_started_part_four.md)"
 
 A **tutorial** requires a clear **step-by-step** guidance to achieve a singular objective. It brings you from A to B, describing precisely all the necessary steps involved in that process, showing each of the 5 steps to go from A to B.
 It does not only describes steps 2 and 3, but also shows you how to accomplish them.
diff --git a/doc/user/project/pages/getting_started_part_four.md b/doc/user/project/pages/getting_started_part_four.md
index e338e1d8085..e4ee2f7cdfa 100644
--- a/doc/user/project/pages/getting_started_part_four.md
+++ b/doc/user/project/pages/getting_started_part_four.md
@@ -1,4 +1,5 @@
 ---
+last_updated: 2018-02-16
 author: Marcia Ramos
 author_gitlab: marcia
 level: intermediate
@@ -6,14 +7,7 @@ article_type: user guide
 date: 2017-02-22
 ---
 
-# GitLab Pages from A to Z: Part 4
-
-- [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)
-- [Part 3: Setting Up Custom Domains - DNS Records and SSL/TLS Certificates](getting_started_part_three.md)
-- **Part 4: Creating and tweaking `.gitlab-ci.yml` for GitLab Pages**
-
-## Creating and Tweaking `.gitlab-ci.yml` for GitLab Pages
+# Creating and Tweaking GitLab CI/CD for GitLab Pages
 
 [GitLab CI](https://about.gitlab.com/gitlab-ci/) serves
 numerous purposes, to build, test, and deploy your app
@@ -22,10 +16,13 @@ from GitLab through
 methods. You will need it to build your website with GitLab Pages,
 and deploy it to the Pages server.
 
+To implement GitLab CI/CD, the first thing we need is a configuration
+file called `.gitlab-ci.yml` placed at your website's root directory.
+
 What this file actually does is telling the
 [GitLab Runner](https://docs.gitlab.com/runner/) to run scripts
 as you would do from the command line. The Runner acts as your
-terminal. GitLab CI tells the Runner which commands to run.
+terminal. GitLab CI/CD tells the Runner which commands to run.
 Both are built-in in GitLab, and you don't need to set up
 anything for them to work.
 
@@ -37,7 +34,7 @@ need to understand just a few things to be able to write our own
 with its own syntax. You can always check your CI syntax with
 the [GitLab CI Lint Tool](https://gitlab.com/ci/lint).
 
-**Practical Example:**
+## Practical example
 
 Let's consider you have a [Jekyll](https://jekyllrb.com/) site.
 To build it locally, you would open your terminal, and run `jekyll build`.
@@ -387,7 +384,3 @@ in parallel, or build a custom pipeline](https://about.gitlab.com/2016/07/29/the
 [pulling specific directories from different projects](https://about.gitlab.com/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/)
 to deploy this website you're looking at, docs.gitlab.com.
 - On this blog post, we teach you [how to use GitLab Pages to produce a code coverage report](https://about.gitlab.com/2016/11/03/publish-code-coverage-report-with-gitlab-pages/).
-
-|||
-|:--|--:|
-|[**← Part 3: Setting Up Custom Domains - DNS Records and SSL/TLS Certificates**](getting_started_part_three.md)||
diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md
index 19f42890428..290dfa5af84 100644
--- a/doc/user/project/pages/getting_started_part_one.md
+++ b/doc/user/project/pages/getting_started_part_one.md
@@ -1,4 +1,5 @@
 ---
+last_updated: 2018-02-16
 author: Marcia Ramos
 author_gitlab: marcia
 level: beginner
@@ -6,29 +7,22 @@ article_type: user guide
 date: 2017-02-22
 ---
 
-# GitLab Pages from A to Z: Part 1
+# Static sites and GitLab Pages domains
 
-- **Part 1: Static sites and GitLab Pages domains**
-- [Part 2: Quick start guide - Setting up GitLab Pages](getting_started_part_two.md)
-- [Part 3: Setting Up Custom Domains - DNS Records and SSL/TLS Certificates](getting_started_part_three.md)
-- [Part 4: Creating and tweaking `.gitlab-ci.yml` for GitLab Pages](getting_started_part_four.md)
-
-## GitLab Pages from A to Z
-
-This is a comprehensive guide, made for those who want to
+This document is the beginning of a comprehensive guide, made for those who want to
 publish a website with GitLab Pages but aren't familiar with
 the entire process involved.
 
-This [first part](#what-you-need-to-know-before-getting-started) of this series will present you to the concepts of
+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 part](getting_started_part_two.md) covers how to get started with GitLab Pages: deploy
+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 part](getting_started_part_three.md) will show you how to set up a custom domain or subdomain
+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 part](getting_started_part_four.md) will show you how to create and tweak GitLab CI for
+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)
@@ -116,6 +110,4 @@ You can only create the highest level group website.
 - On your GitLab instance, replace `gitlab.io` above with your
 Pages server domain. Ask your sysadmin for this information.
 
-|||
-|:--|--:|
-||[**Part 2: Quick start guide - Setting up GitLab Pages →**](getting_started_part_two.md)|
+_Read on about [Projects for GitLab Pages and URL structure](getting_started_part_two.md)._
diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md
index a3e12107c39..b6cf68a02a2 100644
--- a/doc/user/project/pages/getting_started_part_three.md
+++ b/doc/user/project/pages/getting_started_part_three.md
@@ -1,5 +1,5 @@
 ---
-last_updated: 2017-09-28
+last_updated: 2018-02-16
 author: Marcia Ramos
 author_gitlab: marcia
 level: beginner
@@ -7,20 +7,13 @@ article_type: user guide
 date: 2017-02-22
 ---
 
-# GitLab Pages from A to Z: Part 3
+# GitLab Pages custom domains and SSL/TLS Certificates
 
-- [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)
-- **Part 3: Setting Up Custom Domains - DNS Records and SSL/TLS Certificates**
-- [Part 4: Creating and tweaking `.gitlab-ci.yml` for GitLab Pages](getting_started_part_four.md)
-
-## Setting Up Custom Domains - DNS Records and SSL/TLS Certificates
-
-As described in the previous part of this series, setting up GitLab Pages with custom domains, and adding SSL/TLS certificates to them, are optional features of GitLab Pages.
+Setting up GitLab Pages with custom domains, and adding SSL/TLS certificates to them, are optional features of GitLab Pages.
 
 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
+## 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:
@@ -35,7 +28,7 @@ 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
+## DNS Records
 
 A Domain Name System (DNS) web service routes visitors to websites
 by translating domain names (such as `www.example.com`) into the
@@ -71,7 +64,7 @@ for the most popular hosting services:
 If your hosting service is not listed above, you can just try to
 search the web for "how to add dns record on <my hosting service>".
 
-#### DNS A record
+### DNS A record
 
 In case you want to point a root domain (`example.com`) to your
 GitLab Pages site, deployed to `namespace.gitlab.io`, you need to
@@ -86,7 +79,7 @@ running on your instance).
 
 ![DNS A record pointing to GitLab.com Pages server](img/dns_add_new_a_record_example_updated.png)
 
-#### DNS CNAME record
+### DNS CNAME record
 
 In case you want to point a subdomain (`hello-world.example.com`)
 to your GitLab Pages site initially deployed to `namespace.gitlab.io`,
@@ -102,7 +95,7 @@ without any `/project-name`.
 
 ![DNS CNAME record pointing to GitLab.com project](img/dns_cname_record_example.png)
 
-#### TL;DR
+### TL;DR
 
 | From | DNS Record | To |
 | ---- | ---------- | -- |
@@ -118,7 +111,7 @@ 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
+## 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
@@ -141,7 +134,7 @@ 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
+## SSL/TLS Certificates
 
 Every GitLab Pages project on GitLab.com will be available under
 HTTPS for the default Pages domain (`*.gitlab.io`). Once you set
@@ -157,7 +150,7 @@ highly recommendable.
 Let's start with an introduction to the importance of HTTPS.
 Alternatively, jump ahead to [adding certificates to your project](#adding-certificates-to-your-project).
 
-#### Why should I care about HTTPS?
+### Why should I care about HTTPS?
 
 This might be your first question. If our sites are hosted by GitLab Pages,
 they are static, hence we are not dealing with server-side scripts
@@ -178,7 +171,7 @@ authentications and validations.
 How about taking Josh's advice and protecting our sites too? We will be
 well supported, and we'll contribute to a safer internet.
 
-#### Organizations supporting HTTPS
+### Organizations supporting HTTPS
 
 There is a huge movement in favor of securing all the web. W3C fully
 [supports the cause](https://w3ctag.github.io/web-https/) and explains very well
@@ -188,7 +181,7 @@ and would no longer accept unsecured connections. Recently, Mozilla published a
 [communication](https://blog.mozilla.org/security/2016/03/29/march-2016-ca-communication/)
 reiterating the importance of HTTPS.
 
-### Issuing Certificates
+## Issuing Certificates
 
 GitLab Pages accepts [PEM](https://support.quovadisglobal.com/kb/a37/what-is-pem-format.aspx) certificates issued by
 [Certificate Authorities (CA)](https://en.wikipedia.org/wiki/Certificate_authority)
@@ -217,7 +210,7 @@ Their certs are valid up to 15 years. Read through the tutorial on
 Regardless the CA you choose, the steps to add your certificate to
 your Pages project are the same.
 
-#### What do you need
+### What do you need
 
 1. A PEM certificate
 1. An intermediate certificate
@@ -227,7 +220,7 @@ your Pages project are the same.
 
 These fields are found under your **Project**'s **Settings** > **Pages** > **New Domain**.
 
-#### What's what?
+### What's what?
 
 - A PEM certificate is the certificate generated by the CA,
 which needs to be added to the field **Certificate (PEM)**.
@@ -240,7 +233,7 @@ are one of these cases.
 - A public key is an encrypted key which validates
 your PEM against your domain.
 
-#### Now what?
+### Now what?
 
 Now that you hopefully understand why you need all
 of this, it's simple:
@@ -257,6 +250,4 @@ just jumping a line between them.
 regular text editors. Always use code editors (such as
 Sublime Text, Atom, Dreamweaver, Brackets, etc).
 
-|||
-|:--|--:|
-|[**← Part 2: Quick start guide - Setting up GitLab Pages**](getting_started_part_two.md)|[**Part 4: Creating and tweaking `.gitlab-ci.yml` for GitLab Pages →**](getting_started_part_four.md)|
+_Read on about [Creating and Tweaking GitLab CI/CD for GitLab Pages](getting_started_part_four.md)_
diff --git a/doc/user/project/pages/getting_started_part_two.md b/doc/user/project/pages/getting_started_part_two.md
index 06f706b83f5..2274cac8ace 100644
--- a/doc/user/project/pages/getting_started_part_two.md
+++ b/doc/user/project/pages/getting_started_part_two.md
@@ -1,4 +1,5 @@
 ---
+last_updated: 2018-02-16
 author: Marcia Ramos
 author_gitlab: marcia
 level: beginner
@@ -6,25 +7,17 @@ article_type: user guide
 date: 2017-02-22
 ---
 
-# GitLab Pages from A to Z: Part 2
-
-- [Part 1: Static sites and GitLab Pages domains](getting_started_part_one.md)
-- **Part 2: Quick start guide - Setting up GitLab Pages**
-- [Part 3: Setting Up Custom Domains - DNS Records and SSL/TLS Certificates](getting_started_part_three.md)
-- [Part 4: Creating and tweaking `.gitlab-ci.yml` for GitLab Pages](getting_started_part_four.md)
-
-## Setting up GitLab Pages
-
-For a complete step-by-step tutorial, please read the
-blog post [Hosting on GitLab.com with GitLab Pages](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/). The following sections will explain
-what do you need and why do you need them.
+# Projects for GitLab Pages and URL structure
 
 ## What you need to get started
 
+To get started with GitLab Pages, you need:
+
 1. A project
 1. A configuration file (`.gitlab-ci.yml`) to deploy your site
 1. A specific `job` called `pages` in the configuration file
 that will make GitLab aware that you are deploying a GitLab Pages website
+1. A `public` directory with the content of the website
 
 Optional Features:
 
@@ -54,35 +47,26 @@ containing the most popular SSGs templates.
 Watch the [video tutorial](https://youtu.be/TWqh9MtT4Bg) we've
 created for the steps below.
 
-1. Choose your SSG template
-1. Fork a project from the [Pages group](https://gitlab.com/pages)
-1. Remove the fork relationship by navigating to your **Project**'s **Settings** > **Edit Project**
+1. [Fork a sample project](../../../gitlab-basics/fork-project.md) from the [Pages group](https://gitlab.com/pages)
+1. Trigger a build (push a change to any file)
+1. As soon as the build passes, your website will have been deployed with GitLab Pages. Your website URL will be available under your project's **Settings** > **Pages**
+1. Optionally, remove the fork relationship by navigating to your project's **Settings** > expanding **Advanced settings** and scrolling down to **Remove fork relashionship**:
 
     ![remove fork relashionship](img/remove_fork_relashionship.png)
 
-1. Enable Shared Runners for your fork: navigate to your **Project**'s **Settings** > **Pipelines**
-1. Trigger a build (push a change to any file)
-1. As soon as the build passes, your website will have been deployed with GitLab Pages. Your website URL will be available under your **Project**'s **Settings** > **Pages**
-
 To turn a **project website** forked from the Pages group into a **user/group** website, you'll need to:
 
-- Rename it to `namespace.gitlab.io`: navigate to **Project**'s **Settings** > **Edit Project** > **Rename repository**
+- Rename it to `namespace.gitlab.io`: navigate to project's **Settings** > expand **Advanced settings** > and scroll down to **Rename repository**
 - Adjust your SSG's [base URL](#urls-and-baseurls) to from `"project-name"` to `""`. This setting will be at a different place for each SSG, as each of them have their own structure and file tree. Most likelly, it will be in the SSG's config file.
 
 > **Notes:**
 >
->1. Why do I need to remove the fork relationship?
+> Why do I need to remove the fork relationship?
 >
->     Unless you want to contribute to the original project,
+> Unless you want to contribute to the original project,
 you won't need it connected to the upstream. A
 [fork](https://about.gitlab.com/2016/12/01/how-to-keep-your-fork-up-to-date-with-its-origin/#fork)
 is useful for submitting merge requests to the upstream.
->
-> 2. Why do I need to enable Shared Runners?
->
->     Shared Runners will run the script set by your GitLab CI/CD
-configuration file. They're enabled by default to new projects,
-but not to forks.
 
 ### Create a project from scratch
 
@@ -111,7 +95,7 @@ where you'll find its default URL.
 > - GitLab Pages [supports any SSG](https://about.gitlab.com/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/), but,
 if you don't find yours among the templates, you'll need
 to configure your own `.gitlab-ci.yml`. Do do that, please
-read through the article [Creating and Tweaking `.gitlab-ci.yml` for GitLab Pages](getting_started_part_four.md). New SSGs are very welcome among
+read through the article [Creating and Tweaking GitLab CI/CD for GitLab Pages](getting_started_part_four.md). New SSGs are very welcome among
 the [example projects](https://gitlab.com/pages). If you set
 up a new one, please
 [contribute](https://gitlab.com/pages/pages.gitlab.io/blob/master/CONTRIBUTING.md)
@@ -124,7 +108,7 @@ you can run `git init` in your local website directory, add the
 remote URL: `git remote add origin git@gitlab.com:namespace/project-name.git`,
 then add, commit, and push.
 
-### URLs and Baseurls
+## URLs and Baseurls
 
 Every Static Site Generator (SSG) default configuration expects
 to find your website under a (sub)domain (`example.com`), not
@@ -152,11 +136,7 @@ example we've just mentioned, you'd have to change Jekyll's `_config.yml` to:
 baseurl: ""
 ```
 
-### Custom Domains
+## Custom Domains
 
-GitLab Pages supports custom domains and subdomains, served under HTTPS or HTTPS.
+GitLab Pages supports custom domains and subdomains, served under HTTP or HTTPS.
 Please check the [next part](getting_started_part_three.md) of this series for an overview.
-
-|||
-|:--|--:|
-|[**← Part 1: Static sites, domains, DNS records, and SSL/TLS certificates**](getting_started_part_one.md)|[**Setting Up Custom Domains - DNS Records and SSL/TLS Certificates →**](getting_started_part_three.md)|
diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md
index df245710940..a65aa758198 100644
--- a/doc/user/project/pages/index.md
+++ b/doc/user/project/pages/index.md
@@ -37,10 +37,10 @@ to secure them.
 
 Read the following tutorials to know more about:
 
-- [Static websites and GitLab Pages domains](getting_started_part_one.md)
-- [Forking projects and creating new ones from scratch, URLs and baseurls](getting_started_part_two.md)
-- [Custom domains and subdomains, DNS records, SSL/TLS certificates](getting_started_part_three.md)
-- [How to create your own `.gitlab-ci.yml` for your site](getting_started_part_four.md)
+- [Static websites and GitLab Pages domains](getting_started_part_one.md): Understand what is a static website, and how GitLab Pages default domains work
+- [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
+- [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)
 - [Hosting on GitLab.com with GitLab Pages](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/) (outdated)