Merge branch 'docs-50507-pages-overview' into 'master'

Docs: improve Pages overview (to deprecate feature page)

Closes #50507

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

9 files changed, 148 insertions, 40 deletions

diff --git a/doc/user/project/pages/img/icons/click.png b/doc/user/project/pages/img/icons/click.png
new file mode 100644
index 00000000000..daaf760ec08
--- /dev/null
+++ b/doc/user/project/pages/img/icons/click.png
diff --git a/doc/user/project/pages/img/icons/cogs.png b/doc/user/project/pages/img/icons/cogs.png
new file mode 100644
index 00000000000..a12da1b5e8c
--- /dev/null
+++ b/doc/user/project/pages/img/icons/cogs.png
diff --git a/doc/user/project/pages/img/icons/fork.png b/doc/user/project/pages/img/icons/fork.png
new file mode 100644
index 00000000000..e2c9577e7ce
--- /dev/null
+++ b/doc/user/project/pages/img/icons/fork.png
diff --git a/doc/user/project/pages/img/icons/free.png b/doc/user/project/pages/img/icons/free.png
new file mode 100644
index 00000000000..3b8f8f6863e
--- /dev/null
+++ b/doc/user/project/pages/img/icons/free.png
diff --git a/doc/user/project/pages/img/icons/lock.png b/doc/user/project/pages/img/icons/lock.png
new file mode 100644
index 00000000000..1c1f0b4457b
--- /dev/null
+++ b/doc/user/project/pages/img/icons/lock.png
diff --git a/doc/user/project/pages/img/icons/monitor.png b/doc/user/project/pages/img/icons/monitor.png
new file mode 100644
index 00000000000..7b99d430eef
--- /dev/null
+++ b/doc/user/project/pages/img/icons/monitor.png
diff --git a/doc/user/project/pages/img/icons/terminal.png b/doc/user/project/pages/img/icons/terminal.png
new file mode 100644
index 00000000000..ab5ae11310c
--- /dev/null
+++ b/doc/user/project/pages/img/icons/terminal.png
diff --git a/doc/user/project/pages/img/ssgs_pages.png b/doc/user/project/pages/img/ssgs_pages.png
new file mode 100644
index 00000000000..608881c8e31
--- /dev/null
+++ b/doc/user/project/pages/img/ssgs_pages.png
diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md
index 4f0774dba5c..60144fa1971 100644
--- a/doc/user/project/pages/index.md
+++ b/doc/user/project/pages/index.md
@@ -4,71 +4,180 @@ description: 'Learn how to use GitLab Pages to deploy a static website at no add
 
 # GitLab Pages
 
-With GitLab Pages it's easy to publish your project website. GitLab Pages is a hosting service for static websites, at no additional cost.
-
-## Getting Started
-
-[Create a project from scratch](getting_started_part_two.md#create-a-project-from-scratch)
-to get you started quickly, or,
-alternatively, start from an existing project as follows:
-
-1. [Fork](../../../gitlab-basics/fork-project.md#how-to-fork-a-project) an [example project](https://gitlab.com/pages):
+**GitLab Pages is a feature that allows you to publish static websites
+directly from a repository in GitLab.**
+
+You can use it either for personal or business websites, such as
+portfolios, documentation, manifestos, and business presentations,
+and attribute any license to your content.
+
+<table class="borderless-table center fixed-table">
+  <tr>
+    <td style="width: 22%"><img src="img/icons/cogs.png" alt="SSGs" class="image-noshadow half-width"></td>
+    <td style="width: 4%">
+      <strong>
+        <i class="fa fa-angle-double-right" aria-hidden="true"></i>
+      </strong>
+    </td>
+    <td style="width: 22%"><img src="img/icons/monitor.png" alt="Websites" class="image-noshadow half-width"></td>
+    <td style="width: 4%">
+      <strong>
+        <i class="fa fa-angle-double-right" aria-hidden="true"></i>
+      </strong>
+    </td>
+    <td style="width: 22%"><img src="img/icons/free.png" alt="Pages is free" class="image-noshadow half-width"></td>
+    <td style="width: 4%">
+      <strong>
+        <i class="fa fa-angle-double-right" aria-hidden="true"></i>
+      </strong>
+    </td>
+    <td style="width: 22%"><img src="img/icons/lock.png" alt="Secure your website" class="image-noshadow half-width"></td>
+  </tr>
+  <tr>
+    <td><em>Use any static website generator or plain HTML</em></td>
+    <td></td>
+    <td><em>Create websites for your projects, groups, or user account</em></td>
+    <td></td>
+    <td><em>Host on GitLab.com for free, or on your own GitLab instance</em></td>
+    <td></td>
+    <td><em>Connect your custom domain(s) and TLS certificates</em></td>
+  </tr>
+</table>
+
+Pages is available for free for all GitLab.com users as well as for self-managed
+instances (GitLab Core, Starter, Premium, and Ultimate).
+
+## Overview
+
+<div class="row">
+<div class="col-md-9">
+<p style="margin-top: 18px;">
+To publish a website with Pages, you can use any Static Site Generator (SSG),
+such as Jekyll, Hugo, Middleman, Harp, Hexo, and Brunch, just to name a few. You can also
+publish any website written directly in plain HTML, CSS, and JavaScript.</p>
+<p>Pages does <strong>not</strong> support dynamic server-side processing, for instance, as <code>.php</code> and <code>.asp</code> requires. See this article to learn more about
+<a href="https://about.gitlab.com/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/">static websites vs dynamic websites</a>.</p>
+</div>
+<div class="col-md-3"><img src="img/ssgs_pages.png" alt="Examples of SSGs supported by Pages" class="image-noshadow middle display-block"></div>
+</div>
+
+### Availability
+
+If you're using GitLab.com, your website will be publicly available to the internet.
+If you're using self-managed instances (Core, Starter, Premium, or Ultimate),
+your websites will be published on your own server, according to the
+[Pages admin settings](../../../administration/pages/index.md) chosen by your sysdamin,
+who can opt for making them public or internal to your server.
+
+### How it works
+
+To use GitLab Pages, first you need to create a project in GitLab to upload your website's
+files to. These projects can be either public, internal, or private, at your own choice.
+GitLab will always deploy your website from a very specific folder called `public` in your
+repository. Note that when you create a new project in GitLab, a [repository](../repository/index.md)
+becomes available automatically.
+
+To deploy your site, GitLab will use its built-in tool called [GitLab CI/CD](../../../ci/README.md),
+that will build your site and publish it to the GitLab Pages server. The sequence of
+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),
+`*.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.
+
+Optionally, when adding your own domain, you can add an SSL/TLS certificate to secure your
+site under the HTTPS protocol.
+
+## Getting started
+
+To get started with GitLab Pages, you can either [create a project from scratch](getting_started_part_two.md#create-a-project-from-scratch)
+or quickly start from copying an existing example project, as follows:
+
+1. Choose an [example project](https://gitlab.com/pages) to [fork](../../../gitlab-basics/fork-project.md#how-to-fork-a-project):
    by forking a project, you create a copy of the codebase you're forking from to start from a template instead of starting from scratch.
-2. Change a file to trigger a GitLab CI/CD pipeline: GitLab CI/CD will build and deploy your site to GitLab Pages.
-3. Visit your project's **Settings > Pages** to see your **website link**, and click on it. Bam! Your website is live! :)
-
-    _Further steps (optional):_
-
-4. Remove the [fork relationship](getting_started_part_two.md#fork-a-project-to-get-started-from)
+1. From the left sidebar, navigate to your project's **CI/CD > Pipelines** and click
+**Run pipeline** so that GitLab CI/CD will build and deploy your site to the server.
+1. Once the pipeline has finished successfully, find the link to visit your website from your
+   project's **Settings > Pages**.
+
+<table class="borderless-table center fixed-table middle width-80">
+  <tr>
+    <td style="width: 30%"><img src="img/icons/fork.png" alt="Fork" class="image-noshadow half-width"></td>
+    <td style="width: 10%">
+      <strong>
+        <i class="fa fa-angle-double-right" aria-hidden="true"></i>
+      </strong>
+    </td>
+    <td style="width: 30%"><img src="img/icons/terminal.png" alt="Deploy" class="image-noshadow half-width"></td>
+    <td style="width: 10%">
+      <strong>
+        <i class="fa fa-angle-double-right" aria-hidden="true"></i>
+      </strong>
+    </td>
+    <td style="width: 30%"><img src="img/icons/click.png" alt="Visit" class="image-noshadow half-width"></td>
+  </tr>
+  <tr>
+    <td><em>Fork an example project</em></td>
+    <td></td>
+    <td><em>Deploy your website</em></td>
+    <td></td>
+    <td><em>Visit your website's URL</em></td>
+  </tr>
+</table>
+
+Your website is then visible on your domain, and you can modify your files
+as you wish. For every modification pushed to your repository, GitLab CI/CD will run
+a new pipeline to publish your changes to the server.
+
+You can also take some optional further steps:
+
+- Remove the [fork relationship](getting_started_part_two.md#fork-a-project-to-get-started-from)
    (_You don't need the relationship unless you intent to contribute back to the example project you forked from_).
-5. Make it a [user/group website](getting_started_part_one.md#user-and-group-websites)
+- Make it a [user/group website](getting_started_part_one.md#user-and-group-websites)
 
-**Watch a video with the steps above: https://www.youtube.com/watch?v=TWqh9MtT4Bg**
+**<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video tutorial](https://www.youtube.com/watch?v=TWqh9MtT4Bg) with all the steps above!**
 
 _Advanced options:_
 
 - [Use a custom domain](getting_started_part_three.md#adding-your-custom-domain-to-gitlab-pages)
 - Apply [SSL/TLS certification](getting_started_part_three.md#ssl-tls-certificates) to your custom domain
 
-## How Does It Work?
-
-With GitLab Pages you can create [static websites](getting_started_part_one.md#what-you-need-to-know-before-getting-started)
-for your GitLab projects, groups, or user accounts.
-
-It supports plain static content, such as HTML, and **all** [static site generators (SSGs)](https://about.gitlab.com/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/), such as Jekyll, Middleman, Hexo, Hugo, and Pelican.
-
-Connect as many custom domains as you like and bring your own TLS certificate
-to secure them.
-
-Your files live in a project [repository](../repository/index.md) on GitLab.
-[GitLab CI](../../../ci/README.md) picks up those files and makes them available at, typically,
-`https://<username>.gitlab.io/<projectname>`. Please read through the docs on 
-[GitLab Pages domains](getting_started_part_one.md#gitlab-pages-domain) for more info.
-
 ## Explore GitLab Pages
 
-Read the following tutorials to know more about:
+To learn more about GitLab Pages, read the following tutorials:
 
 - [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
+- [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)
 
-_Blog posts series about Static Site Generators (SSGs):_
+### GitLab Pages with Static Site Generators (SSGs)
+
+To understand more about SSGs, their advantages, and how to get the most from them
+with Pages, read through this series:
 
 - [SSGs part 1: Static vs dynamic websites](https://about.gitlab.com/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/)
 - [SSGs part 2: Modern static site generators](https://about.gitlab.com/2016/06/10/ssg-overview-gitlab-pages-part-2/)
 - [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/)
 
-_Blog posts for securing GitLab Pages custom domains with SSL/TLS certificates:_
+### GitLab Pages with SSL/TLS certificates
+
+If you're using GitLab Pages default domain (`.gitlab.io`), your website will be 
+automatically secure and available under HTTPS. If you're using your own domain, you can
+optionally secure it with with SSL/TLS certificates. You can read the following
+tutorials to learn how to use these third-party certificates with GitLab Pages:
 
 - [CloudFlare](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/)
-- [Let's Encrypt](https://about.gitlab.com/2016/04/11/tutorial-securing-your-gitlab-pages-with-tls-and-letsencrypt/) (outdated)
+- [Let's Encrypt](https://about.gitlab.com/2016/04/11/tutorial-securing-your-gitlab-pages-with-tls-and-letsencrypt/) (mind that although this article is out-of-date, it can still be useful to guide you through the basic steps)
 
 ## Advanced use
 
+There are quite some great examples of GitLab Pages websites built for some
+specific reasons. These examples can teach you some advanced techniques
+to use and adapt to your own needs:
+
 - [Posting to your GitLab Pages blog from iOS](https://about.gitlab.com/2016/08/19/posting-to-your-gitlab-pages-blog-from-ios/)
 - [GitLab CI: Run jobs sequentially, in parallel, or build a custom pipeline](https://about.gitlab.com/2016/07/29/the-basics-of-gitlab-ci/)
 - [GitLab CI: Deployment & environments](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/)
@@ -80,10 +189,9 @@ _Blog posts for securing GitLab Pages custom domains with SSL/TLS certificates:_
 Enable and configure GitLab Pages on your own instance (GitLab Community Edition and Enterprise Editions) with
 the [admin guide](../../../administration/pages/index.md).
 
-**Watch the video: https://www.youtube.com/watch?v=dD8c7WNcc6s**
+**<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video tutorial](https://www.youtube.com/watch?v=dD8c7WNcc6s) for getting started with GitLab Pages admin!**
 
 ## More information about GitLab Pages
 
-- For an overview, visit the [feature webpage](https://about.gitlab.com/features/pages/)
 - Announcement (2016-12-24): ["We're bringing GitLab Pages to CE"](https://about.gitlab.com/2016/12/24/were-bringing-gitlab-pages-to-community-edition/)
 - Announcement (2017-03-06): ["We are changing the IP of GitLab Pages on GitLab.com"](https://about.gitlab.com/2017/03/06/we-are-changing-the-ip-of-gitlab-pages-on-gitlab-com/)