diff --git a/doc/pages/getting_started_part_one.md b/doc/pages/getting_started_part_one.md index ed39301df39a8ecbc0d31431cac21bf54eb1fe76..c5b1aa4b65484eedbd739b9f84698c3c7d73706b 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 8acf8a85d5aac56640f2083f199af8c44a156a9c..ef47abef3a0c67a075eece3d4871950922519e22 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 94b9d11e5d5c0b7a7696845efb6af5c02b578256..07dd24122c40b120e2a56727e9c4b8bec24b09a8 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 242fdf3147f9c2bd87c850aecd3b34d4e9d228de..a6f928cc2431bf8d2dad31a421bb52f44b944c84 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)