Docs: Pages - clean up articles
This commit is contained in:
parent
9e9039cef2
commit
4e46909015
|
@ -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.
|
||||
|
|
|
@ -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)||
|
||||
|
|
|
@ -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)._
|
||||
|
|
|
@ -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)_
|
||||
|
|
|
@ -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)|
|
||||
|
|
|
@ -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)
|
||||
|
||||
|
|
Loading…
Reference in New Issue