Merge branch 'docs-pages-intro' into 'master'

Docs: Refactor Pages' intro guide

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

doc/user/group/subgroups/index.md

@@ -167,7 +167,7 @@ Here's a list of what you can't do with subgroups:
 - [GitLab Pages](../../project/pages/index.md) supports projects hosted under
   a subgroup, but not subgroup websites.
   That means that only the highest-level group supports
-  [group websites](../../project/pages/introduction.html#user-or-group-pages),
+  [group websites](../../project/pages/getting_started_part_one.md#gitlab-pages-domain-names),
   although you can have project websites under a subgroup.
 - It is not possible to share a project with a group that's an ancestor of
   the group the project is in. That means you can only share as you walk down

doc/user/project/pages/getting_started_part_one.md

 ---
 last_updated: 2018-02-16
-author: Marcia Ramos
-author_gitlab: marcia
-level: beginner
-article_type: user guide
-date: 2017-02-22
 ---
 
 # Static sites and GitLab Pages domains
 
-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 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 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 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 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)
-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).
-
->**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.
+On this docucument, learn how to name your project for GitLab Pages
+according to your intended website's URL.
 
 ## Static sites
 
@@ -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,
 which is highly recommendable and much faster than hardcoding.
 
-### 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
-
-## GitLab Pages domain
+See the [further reading](#further-reading) section below for
+references on static site concepts.
 
-If you set up a GitLab Pages project on GitLab.com,
-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.
+## GitLab Pages domain names
 
 >**Note:**
 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,
 you just need to replace Pages wildcard domain on GitLab.com
 (`*.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`|
 
-### Practical examples
+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.
 
-#### Project Websites
+To understand Pages domains clearly, read the examples below.
+
+### Project website examples
 
 - You created a project called `blog` under your username `john`,
   therefore your project URL is `https://gitlab.com/john/blog/`.
@@ -92,7 +72,7 @@ Learn more about [namespaces](../../group/index.md#namespaces).
   GitLab Pages for this project, the site will live under
   `https://engineering.gitlab.io/docs/workflows`.
 
-#### User and Group Websites
+### User and Group website examples
 
 - Under your username, `john`, you created a project called
   `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).
   Once you enable GitLab Pages for your project,
   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:**
 
 - On GitLab.com, a project site will always be available under
@@ -115,3 +93,10 @@ Learn more about [namespaces](../../group/index.md#namespaces).
   Pages server domain. Ask your sysadmin for this information.
 
 _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
\ No newline at end of file

doc/user/project/pages/getting_started_part_three.md

@@ -177,9 +177,6 @@ Note that [DNS propagation may take some time (up to 24h)](http://www.inmotionho
 although it's usually a matter of minutes to complete. Until it does, verification
 will fail and attempts to visit 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.
-
 ### Redirecting `www.domain.com` to `domain.com` with Cloudflare
 
 If you use Cloudflare, you can redirect `www` to `domain.com` without the need of adding both

doc/user/project/pages/getting_started_part_two.md

@@ -104,8 +104,8 @@ from the Pages group into a **user/group** website, you'll need to:
 ### Create a project from scratch
 
 1. From your **Project**'s **[Dashboard](https://gitlab.com/dashboard/projects)**,
-   click **New project**, and name it considering the
-   [practical examples](getting_started_part_one.md#practical-examples).
+   click **New project**, and name it according to the
+   [Pages domain names](getting_started_part_one.md#gitlab-pages-domain-names).
 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/CD**:

doc/user/project/pages/index.md

@@ -5,6 +5,11 @@ last_updated: 2019-03-05
 
 # GitLab Pages
 
+> - [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
 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
 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.
 
-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
 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:
 - [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)
+- [Exploring GitLab Pages](introduction.md): Technical aspects, specific configuration options, custom 404 pages, limitations
 
 ### GitLab Pages with Static Site Generators (SSGs)