Merge branch 'pages-guides' into 'master'

Fix missing link from Pages guides

See merge request !9450

5 files changed, 47 insertions, 40 deletions

diff --git a/doc/pages/getting_started_part_one.md b/doc/pages/getting_started_part_one.md
index ed39301df39..c5b1aa4b654 100644
--- a/doc/pages/getting_started_part_one.md
+++ b/doc/pages/getting_started_part_one.md
@@ -1,9 +1,5 @@
 # GitLab Pages from A to Z: Part 1
 
-> Type: user guide
->
-> Level: beginner
-
 - **Part 1: Static Sites, Domains, DNS Records, and SSL/TLS Certificates**
 - _[Part 2: Quick Start Guide - Setting Up GitLab Pages](getting_started_part_two.md)_
 - _[Part 3: Creating and Tweaking `.gitlab-ci.yml` for GitLab Pages](getting_started_part_three.md)_
@@ -19,14 +15,15 @@ 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).
 
-> For this guide, we assume you already have GitLab Pages
+>**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
 
 GitLab Pages only supports static websites, meaning,
 your output files must be HTML, CSS, and JavaScript only.
@@ -43,7 +40,7 @@ which is highly recommendable and much faster than hardcoding.
 - 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
+### GitLab Pages domain
 
 If you set up a GitLab Pages project on GitLab.com,
 it will automatically be accessible under a
@@ -51,7 +48,8 @@ it will automatically be accessible under a
 The `namespace` is defined by your username on GitLab.com,
 or the group name you created this project under.
 
-> Note: If you use your own GitLab instance to deploy your
+>**Note:**
+If you use your own GitLab instance to deploy your
 site with GitLab Pages, check with your sysadmin what's your
 Pages wildcard domain. This guide is valid for any GitLab instance,
 you just need to replace Pages wildcard domain on GitLab.com
@@ -180,7 +178,8 @@ up your Pages project with your custom (sub)domain, if you want
 it secured by HTTPS, you will have to issue a certificate for that
 (sub)domain and install it on your project.
 
-> Note: certificates are NOT required to add to your custom
+>**Note:**
+Certificates are NOT required to add to your custom
 (sub)domain on your GitLab Pages project, though they are
 highly recommendable.
 
@@ -257,7 +256,8 @@ and paste it in the [same field as your PEM certificate](https://about.gitlab.co
 just jumping a line between them.
 - Copy your public key and paste it in the last field
 
-> Note: **do not** open certificates or encryption keys in
+>**Note:**
+**Do not** open certificates or encryption keys in
 regular text editors. Always use code editors (such as
 Sublime Text, Atom, Dreamweaver, Brackets, etc).
 
diff --git a/doc/pages/getting_started_part_three.md b/doc/pages/getting_started_part_three.md
index 8acf8a85d5a..ef47abef3a0 100644
--- a/doc/pages/getting_started_part_three.md
+++ b/doc/pages/getting_started_part_three.md
@@ -1,16 +1,12 @@
 # GitLab Pages from A to Z: Part 3
 
-> Type: user guide
->
-> Level: intermediate
-
 - _[Part 1: Static Sites, Domains, DNS Records, and SSL/TLS Certificates](getting_started_part_one.md)_
 - _[Part 2: Quick Start Guide - Setting Up GitLab Pages](getting_started_part_two.md)_
 - **Part 3: Creating and Tweaking `.gitlab-ci.yml` for GitLab Pages**
 
 ---
 
-### Creating and Tweaking `.gitlab-ci.yml` for GitLab Pages
+## Creating and Tweaking `.gitlab-ci.yml` for GitLab Pages
 
 [GitLab CI](https://about.gitlab.com/gitlab-ci/) serves
 numerous purposes, to build, test, and deploy your app
@@ -50,7 +46,7 @@ $ gem install jekyll
 $ jekyll build
 ```
 
-#### Script
+### Script
 
 To transpose this script to Yaml, it would be like this:
 
@@ -60,7 +56,7 @@ script:
   - jekyll build
 ```
 
-#### Job
+### Job
 
 So far so good. Now, each `script`, in GitLab is organized by
 a `job`, which is a bunch of scripts and settings you want to
@@ -84,7 +80,7 @@ pages:
   - jekyll build
 ```
 
-#### `public` Dir
+### The `public` directory
 
 We also need to tell Jekyll where do you want the website to build,
 and GitLab Pages will only consider files in a directory called `public`.
@@ -100,7 +96,7 @@ pages:
   - jekyll build -d public
 ```
 
-#### Artifacts
+### Artifacts
 
 We also need to tell the Runner that this _job_ generates
 _artifacts_, which is the site built by Jekyll.
@@ -138,7 +134,7 @@ your Jekyll 3.4.0 site with GitLab Pages. This is the minimum
 configuration for our example. On the steps below, we'll refine
 the script by adding extra options to our GitLab CI.
 
-#### Image
+### Image
 
 At this point, you probably ask yourself: "okay, but to install Jekyll
 I need Ruby. Where is Ruby on that script?". The answer is simple: the
@@ -168,7 +164,8 @@ need to specify which image you want to use, and this image should
 contain NodeJS as part of its file system. E.g., for a
 [Hexo](https://gitlab.com/pages/hexo) site, you can use `image: node:4.2.2`.
 
-> Note: we're not trying to explain what a Docker image is,
+>**Note:**
+We're not trying to explain what a Docker image is,
 we just need to introduce the concept with a minimum viable
 explanation. To know more about Docker images, please visit
 their website or take a look at a
@@ -176,7 +173,7 @@ their website or take a look at a
 
 Let's go a little further.
 
-#### Branching
+### Branching
 
 If you use GitLab as a version control platform, you will have your
 branching strategy to work on your project. Meaning, you will have
@@ -199,7 +196,7 @@ pages:
   - master
 ```
 
-#### Stages
+### Stages
 
 Another interesting concept to keep in mind are build stages.
 Your web app can pass through a lot of tests and other tasks
@@ -272,7 +269,7 @@ tools much more powerful than that. This is what you
 need to be able to create and tweak your builds for
 your GitLab Pages site.
 
-#### Before Script
+### Before Script
 
 To avoid running the same script multiple times across
 your _jobs_, you can add the parameter `before_script`,
@@ -308,7 +305,7 @@ test:
   - master
 ```
 
-#### Caching Dependencies
+### Caching Dependencies
 
 If you want to cache the installation files for your
 projects dependencies, for building faster, you can
@@ -362,7 +359,7 @@ but also **continuously test** pushes to feature-branches,
 **caches** dependencies installed with Bundler, and
 **continuously deploy** every push to the `master` branch.
 
-### Advanced GitLab CI for GitLab Pages
+## Advanced GitLab CI for GitLab Pages
 
 What you can do with GitLab CI is pretty much up to your
 creativity. Once you get used to it, you start creating
@@ -383,4 +380,4 @@ to deploy this website you're looking at, docs.gitlab.com.
 
 |||
 |:--|--:|
-|[**← Part 1: Static sites, domains, DNS records, and SSL/TLS certificates**](getting_started_part_one.md)|[**Part 2: Quick start guide - Setting up GitLab Pages →**](getting_started_part_two.md)|
+|[**← Part 2: Quick start guide - Setting up GitLab Pages**](getting_started_part_two.md)||
diff --git a/doc/pages/getting_started_part_two.md b/doc/pages/getting_started_part_two.md
index 94b9d11e5d5..07dd24122c4 100644
--- a/doc/pages/getting_started_part_two.md
+++ b/doc/pages/getting_started_part_two.md
@@ -10,27 +10,27 @@
 
 ----
 
-## Setting Up GitLab Pages
+## 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.
 
-### What You Need to Get Started
+## What you need to get started
 
 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
 
-#### Optional Features
+Optional Features:
 
 1. A custom domain or subdomain
 1. A DNS pointing your (sub)domain to your Pages site
    1. **Optional**: an SSL/TLS certificate so your custom
    domain is accessible under HTTPS.
 
-### Project
+## Project
 
 Your GitLab Pages project is a regular project created the
 same way you do for the other ones. To get started with GitLab Pages, you have two ways:
@@ -40,7 +40,7 @@ same way you do for the other ones. To get started with GitLab Pages, you have t
 
 Let's go over both options.
 
-#### Fork a Project to Get Started From
+### Fork a project to get started from
 
 To make things easy for you, we've created this
 [group](https://gitlab.com/pages) of default projects
@@ -79,11 +79,11 @@ is useful for submitting merge requests to the upstream.
 configuration file. They're enabled by default to new projects,
 but not to forks.
 
-#### Create a Project from Scratch
+### Create a project from scratch
 
 1. From your **Project**'s **[Dashboard](https://gitlab.com/dashboard/projects)**,
 click **New project**, and name it considering the
-[pratical examples](getting_started_part_one.md#practical-examples).
+[practical examples](getting_started_part_one.md#practical-examples).
 1. Clone it to your local computer, add your website
 files to your project, add, commit and push to GitLab.
 1. From the your **Project**'s page, click **Set up CI**:
diff --git a/doc/pages/index.md b/doc/pages/index.md
index 242fdf3147f..a6f928cc243 100644
--- a/doc/pages/index.md
+++ b/doc/pages/index.md
@@ -1,6 +1,13 @@
 # All you need to know about GitLab Pages
 
-## Product
+With GitLab Pages you can create static websites for your GitLab projects,
+groups, or user accounts. You can use any static website generator: Jekyll,
+Middleman, Hexo, Hugo, Pelican, you name it! Connect as many customs domains
+as you like and bring your own TLS certificate to secure them.
+
+Here's some info we have gathered to get you started.
+
+## General info
 
 - [Product webpage](https://pages.gitlab.io)
 - [We're bringing GitLab Pages to CE](https://about.gitlab.com/2016/12/24/were-bringing-gitlab-pages-to-community-edition/)
@@ -8,12 +15,11 @@
 
 ## Getting started
 
-- [Hosting on GitLab.com with GitLab Pages](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/) a comprehensive step-by-step guide
 - GitLab Pages from A to Z
   - [Part 1: Static sites, domains, DNS records, and SSL/TLS certificates](getting_started_part_one.md)
   - [Part 2: Quick start guide - Setting up GitLab Pages](getting_started_part_two.md)
-      - Video tutorial: [How to publish a website with GitLab Pages on GitLab.com: from a forked project](https://youtu.be/TWqh9MtT4Bg)
   - [Part 3: Creating and tweaking `.gitlab-ci.yml` for GitLab Pages](getting_started_part_three.md)
+- [Hosting on GitLab.com with GitLab Pages](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/) a comprehensive step-by-step guide
 - Secure GitLab Pages custom domain with SSL/TLS certificates
   - [Let's Encrypt](https://about.gitlab.com/2016/04/11/tutorial-securing-your-gitlab-pages-with-tls-and-letsencrypt/)
   - [CloudFlare](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/)
@@ -24,6 +30,11 @@
   - [SSGs part 3: Build any SSG site with GitLab Pages](https://about.gitlab.com/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/)
 - [Posting to your GitLab Pages blog from iOS](https://about.gitlab.com/2016/08/19/posting-to-your-gitlab-pages-blog-from-ios/)
 
+## Video tutorials
+
+- [How to publish a website with GitLab Pages on GitLab.com: from a forked project](https://youtu.be/TWqh9MtT4Bg)
+- [How to Enable GitLab Pages for GitLab CE and EE](https://youtu.be/dD8c7WNcc6s)
+
 ## Advanced use
 
 - Blog Posts:
@@ -32,8 +43,7 @@
   - [Building a new GitLab docs site with Nanoc, GitLab CI, and GitLab Pages](https://about.gitlab.com/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/)
   - [Publish code coverage reports with GitLab Pages](https://about.gitlab.com/2016/11/03/publish-code-coverage-report-with-gitlab-pages/)
 
-## General documentation
+## Specific documentation
 
 - [User docs](../user/project/pages/index.md)
 - [Admin docs](../administration/pages/index.md)
-  - Video tutorial - [How to Enable GitLab Pages for GitLab CE and EE](https://youtu.be/dD8c7WNcc6s)
diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md
index 816600964de..276fbd26835 100644
--- a/doc/user/project/pages/index.md
+++ b/doc/user/project/pages/index.md
@@ -444,6 +444,6 @@ For a list of known issues, visit GitLab's [public issue tracker].
 [public issue tracker]: https://gitlab.com/gitlab-org/gitlab-ee/issues?label_name=Pages
 [ce-14605]: https://gitlab.com/gitlab-org/gitlab-ce/issues/14605
 [quick start guide]: ../../../ci/quick_start/README.md
-[pages-index-guide]: ../../../pages/
+[pages-index-guide]: ../../../pages/index.md
 [pages-quick]: ../../../pages/getting_started_part_one.md
 [video-pages-fork]: https://youtu.be/TWqh9MtT4Bg