Merge branch 'selhorn-pages4' into 'master'

Docs: More Pages work

See merge request gitlab-org/gitlab!33546

doc/user/project/pages/getting_started/fork_sample_project.md

@@ -23,8 +23,8 @@ To fork a sample project and create a Pages website:
 1. Go to your project's **CI/CD > Pipelines** and click **Run pipeline**.
    GitLab CI/CD builds and deploys your site.
 
+The site can take approximately 30 minutes to deploy.
 When the pipeline is finished, go to **Settings > Pages** to find the link to your website from your project.
-It can take approximately 30 minutes to deploy.
 
 For every change pushed to your repository, GitLab CI/CD runs a new pipeline
 that immediately publishes your changes to the Pages site.

doc/user/project/pages/getting_started/new_or_existing_website.md

@@ -5,44 +5,41 @@ group: Release Management
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
 ---
 
-# Start a new Pages website from scratch or deploy an existing website
+# Create a Pages website by using a CI/CD template
 
-If you already have a website and want to deploy it with GitLab Pages,
-or, if you want to start a new site from scratch, you'll need to:
+GitLab provides `.gitlab-ci.yml` templates for the most popular Static Site Generators (SSGs).
+You can create your own `.gitlab-ci.yml` file from one of these templates, and run
+the CI/CD pipeline to generate a Pages website.
 
-- Create a new project in GitLab to hold your site content.
-- Set up GitLab CI/CD to deploy your website to Pages.
+Use a `.gitlab-ci.yml` template when you have an existing project that you want to add a Pages site to.
 
-To do so, follow the steps below.
+1. In the left sidebar, click **Project overview**.
+1. Click **Set up CI/CD**.
 
-1. From your **Project**'s **[Dashboard](https://gitlab.com/dashboard/projects)**,
-   click **New project**, and name it according to the
-   [Pages domain names](../getting_started_part_one.md#gitlab-pages-default-domain-names).
-1. Clone it to your local computer, add your website
-   files to your project, add, commit, and push to GitLab.
-   Alternatively, you can run `git init` in your local directory,
-   add the remote URL:
-   `git remote add origin git@gitlab.com:namespace/project-name.git`,
-   then add, commit, and push to GitLab.
-1. From the your **Project**'s page, click **Set up CI/CD**:
+   ![setup GitLab CI/CD](../img/setup_ci_v13_1.png)
 
-   ![setup GitLab CI/CD](../img/setup_ci.png)
+   If this button is not available, CI/CD is already configured for
+   your project. You may want to browse the `.gitlab-ci.yml` files
+   [in these projects instead](https://gitlab.com/pages).
 
-1. Choose one of the templates from the dropbox menu.
-   Pick up the template corresponding to the SSG you're using (or plain HTML).
+1. From the **Apply a template** list, choose a template for the SSG you're using.
+   You can also choose plain HTML.
 
-   ![gitlab-ci templates](../img/choose_ci_template.png)
+   ![gitlab-ci templates](../img/choose_ci_template_v13_1.png)
 
-   Note that, if you don't find a corresponding template, you can look into
-   [GitLab Pages group of sample projects](https://gitlab.com/pages),
-   you may find one among them that suits your needs, from which you
-   can copy `.gitlab-ci.yml`'s content and adjust for your case.
-   If you don't find it there either, [learn how to write a `.gitlab-ci.yml`
+   If you don't find a corresponding template, you can view the
+   [GitLab Pages group of sample projects](https://gitlab.com/pages).
+   These projects contain `.gitlab-ci.yml` files that you can modify for your needs.
+   You can also [learn how to write your own `.gitlab-ci.yml`
    file for GitLab Pages](../getting_started_part_four.md).
 
-Once you have both site files and `.gitlab-ci.yml` in your project's
-root, GitLab CI/CD will build your site and deploy it with Pages.
-Once the first build passes, you access your site by
-navigating to your **Project**'s **Settings** > **Pages**,
-where you'll find its default URL. It can take approximately 30 min to be
-deployed.
+1. Save and commit the `.gitlab-ci.yml` file.
+
+If everything is configured correctly, the site can take approximately 30 minutes to deploy.
+
+You can watch the pipeline run by going to **CI / CD > Pipelines**.
+When the pipeline is finished, go to **Settings > Pages** to find the link to
+your Pages website.
+
+For every change pushed to your repository, GitLab CI/CD runs a new pipeline
+that immediately publishes your changes to the Pages site.

doc/user/project/pages/getting_started/pages_bundled_template.md

@@ -5,27 +5,30 @@ group: Release Management
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
 ---
 
-# New Pages website from a bundled template
+# Create a Pages website from a new project template
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47857) in GitLab 11.8.
 
-The simplest way to create a GitLab Pages site is to use one of the most
-popular templates, which come already bundled with GitLab and are ready to go.
+GitLab provides templates for the most popular Static Site Generators (SSGs).
+You can create a new project from a template and run the CI/CD pipeline to generate a Pages website.
+
+Use a template when you want to test GitLab Pages or start a new project that's already
+configured to generate a Pages site.
 
 1. From the top navigation, click the **+** button and select **New project**.
 1. Select **Create from Template**.
-1. Choose one of the templates starting with **Pages**:
+1. Next to one of the templates starting with **Pages**, click **Use template**.
 
-   ![Project templates for Pages](../img/pages_project_templates_v11_8.png)
+   ![Project templates for Pages](../img/pages_project_templates_v13_1.png)
 
+1. Complete the form and click **Create project**.
 1. From the left sidebar, navigate to your project's **CI/CD > Pipelines**
    and click **Run pipeline** to trigger GitLab CI/CD to build and deploy your
-   site to the server.
-1. After the pipeline has finished successfully, wait approximately 30 minutes
-   for your website to be visible. After waiting 30 minutes, find the link to
-   visit your website from your project's **Settings > Pages**. If the link
-   leads to a 404 page, wait a few minutes and try again.
-
-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 immediately publish your changes to the server.
+   site.
+
+The site can take approximately 30 minutes to deploy.
+When the pipeline is finished, go to **Settings > Pages** to find the link to
+your Pages website.
+
+For every change pushed to your repository, GitLab CI/CD runs a new pipeline
+that immediately publishes your changes to the Pages site.

doc/user/project/pages/index.md

@@ -16,36 +16,55 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 With GitLab Pages, you can publish static websites
 directly from a repository in GitLab.
 
-- Use for any personal or business website.
-- Use any Static Site Generator (SSG) or plain HTML.
-- Create websites for your projects, groups, or user account.
-- Host your site on your own GitLab instance or on GitLab.com for free.
-- Connect your custom domains and TLS certificates.
-- Attribute any license to your content.
-
 <div class="row">
 <div class="col-md-9">
 <p style="margin-top: 18px;">
-To publish a website with Pages, you can use any SSG,
-like Gatsby, 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. Learn more about
-<a href="https://about.gitlab.com/blog/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/">static websites vs dynamic websites</a>.</p>
-<p>Learn more about GitLab Pages:</p>
+<ul>
+<li>Use for any personal or business website.</li>
+<li>Use any Static Site Generator (SSG) or plain HTML.</li>
+<li>Create websites for your projects, groups, or user account.</li>
+<li>Host your site on your own GitLab instance or on GitLab.com for free.</li>
+<li>Connect your custom domains and TLS certificates.</li>
+<li>Attribute any license to your content.</li>
+</ul>
+</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>
 
+To publish a website with Pages, you can use any SSG,
+like Gatsby, 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.
+
+Pages does **not** support dynamic server-side processing, for instance, as `.php` and `.asp` requires.
+Learn more about
+[static websites compared to dynamic websites](https://about.gitlab.com/blog/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/).
+
+## Getting started
+
+To create a GitLab Pages website:
+
+| Document | Description |
+| -------- | ----------- |
+| [Use a `.gitlab-ci.yml` template](getting_started/new_or_existing_website.md) | Add a Pages site to an existing project. Use a pre-populated CI template file. |
+| [Create a `gitlab-ci.yml` file from scratch](getting_started_part_four.md)    | Add a Pages site to an existing project. Learn how to create and configure your own CI file. |
+| [Use a new project template](getting_started/pages_bundled_template.md)       | Create a new project with Pages already configured by using a new project template. |
+| [Fork a sample project](getting_started/fork_sample_project.md)               | Create a new project with Pages already configured by forking a sample project. |
+
+To update a GitLab Pages website:
+
 | Document | Description |
-| --- | --- |
-| [GitLab Pages domain names, URLs, and baseurls](getting_started_part_one.md) | How GitLab Pages default domains work. |
-| [GitLab CI/CD for GitLab Pages](getting_started_part_four.md) | Create your own site by using `.gitlab-ci.yml`. |
-| [Exploring GitLab Pages](introduction.md) | Requirements, technical aspects, specific GitLab CI/CD configuration options, Access Control, custom 404 pages, limitations, FAQ. |
-|---+---|
-| [Custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md) | Add custom domains and subdomains to your website, configure DNS records and SSL/TLS certificates. |
+| -------- | ----------- |
+| [GitLab Pages domain names, URLs, and baseurls](getting_started_part_one.md) | Learn about GitLab Pages default domains. |
+| [Explore GitLab Pages](introduction.md) | Requirements, technical aspects, specific GitLab CI/CD configuration options, Access Control, custom 404 pages, limitations, FAQ. |
+| [Custom domains and SSL/TLS Certificates](custom_domains_ssl_tls_certification/index.md) | Custom domains and subdomains, DNS records, and SSL/TLS certificates. |
 | [Let's Encrypt integration](custom_domains_ssl_tls_certification/lets_encrypt_integration.md) | Secure your Pages sites with Let's Encrypt certificates, which are automatically obtained and renewed by GitLab. |
 | [CloudFlare certificates](https://about.gitlab.com/blog/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/) | Secure your Pages site with CloudFlare certificates. |
-|---+---|
+
+Learn more and see examples:
+
+| Document | Description |
+| -------- | ----------- |
 | [Static vs dynamic websites](https://about.gitlab.com/blog/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/) | Static versus dynamic site overview. |
 | [Modern static site generators](https://about.gitlab.com/blog/2016/06/10/ssg-overview-gitlab-pages-part-2/) | SSG overview. |
 | [Build any SSG site with GitLab Pages](https://about.gitlab.com/blog/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/) | Use SSGs for GitLab Pages. |
@@ -68,30 +87,18 @@ You can either use GitLab's [default domain for GitLab Pages websites](getting_s
 `*.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.
 
-## Getting started
-
-To get started with GitLab Pages, you can:
-
-- [Use a bundled website template that's ready to go](getting_started/pages_bundled_template.md).
-- [Copy an existing sample](getting_started/fork_sample_project.md).
-- [Create a website from scratch or deploy an existing one](getting_started/new_or_existing_website.md).
+The following diagrams show the workflows you might follow to get started with Pages.
 
 <img src="img/new_project_for_pages_v12_5.png" alt="New projects for GitLab Pages" class="image-noshadow">
 
-Optional features:
-
-- Use a [custom domain or subdomain](custom_domains_ssl_tls_certification/index.md#set-up-pages-with-a-custom-domain).
-- Add an [SSL/TLS certificate to secure your site under the HTTPS protocol](custom_domains_ssl_tls_certification/index.md#adding-an-ssltls-certificate-to-pages).
+## Access to your Pages site
 
 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 custom domain, you can
 optionally secure it with SSL/TLS certificates.
 
-## Access to your Pages site
-
 If you're using GitLab.com, your website will be publicly available to the internet.
-
 To restrict access to your website, enable [GitLab Pages Access Control](pages_access_control.md).
 
 If you're using a self-managed instance (Core, Starter, Premium, or Ultimate),
@@ -113,7 +120,7 @@ to use and adapt to your own needs:
 
 ## Administer GitLab Pages for self-managed instances
 
-Enable and configure GitLab Pages on your own instance (GitLab Community Edition and Enterprise Editions) with
-the [admin guide](../../../administration/pages/index.md).
+If you are running a self-managed instance of GitLab (GitLab Community Edition and Enterprise Editions),
+[follow the administration steps](../../../administration/pages/index.md) to configure Pages.
 
-**<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!**
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a [video tutorial](https://www.youtube.com/watch?v=dD8c7WNcc6s) about how to get started with GitLab Pages administration.