From 5159995edb94c3d4b38820f517dc1689cfba5b11 Mon Sep 17 00:00:00 2001 From: Marcia Ramos Date: Fri, 28 Sep 2018 21:23:15 +0000 Subject: Docs: improve Pages overview (to deprecate feature page) --- doc/user/project/pages/img/icons/click.png | Bin 0 -> 10148 bytes doc/user/project/pages/img/icons/cogs.png | Bin 0 -> 9670 bytes doc/user/project/pages/img/icons/fork.png | Bin 0 -> 9597 bytes doc/user/project/pages/img/icons/free.png | Bin 0 -> 8689 bytes doc/user/project/pages/img/icons/lock.png | Bin 0 -> 7892 bytes doc/user/project/pages/img/icons/monitor.png | Bin 0 -> 5039 bytes doc/user/project/pages/img/icons/terminal.png | Bin 0 -> 4972 bytes doc/user/project/pages/img/ssgs_pages.png | Bin 0 -> 12010 bytes doc/user/project/pages/index.md | 188 ++++++++++++++++++++------ 9 files changed, 148 insertions(+), 40 deletions(-) create mode 100644 doc/user/project/pages/img/icons/click.png create mode 100644 doc/user/project/pages/img/icons/cogs.png create mode 100644 doc/user/project/pages/img/icons/fork.png create mode 100644 doc/user/project/pages/img/icons/free.png create mode 100644 doc/user/project/pages/img/icons/lock.png create mode 100644 doc/user/project/pages/img/icons/monitor.png create mode 100644 doc/user/project/pages/img/icons/terminal.png create mode 100644 doc/user/project/pages/img/ssgs_pages.png 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 Binary files /dev/null and b/doc/user/project/pages/img/icons/click.png differ 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 Binary files /dev/null and b/doc/user/project/pages/img/icons/cogs.png differ 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 Binary files /dev/null and b/doc/user/project/pages/img/icons/fork.png differ 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 Binary files /dev/null and b/doc/user/project/pages/img/icons/free.png differ 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 Binary files /dev/null and b/doc/user/project/pages/img/icons/lock.png differ 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 Binary files /dev/null and b/doc/user/project/pages/img/icons/monitor.png differ 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 Binary files /dev/null and b/doc/user/project/pages/img/icons/terminal.png differ 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 Binary files /dev/null and b/doc/user/project/pages/img/ssgs_pages.png differ 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. + + + + + + + + + + + + + + + + + + + + +
SSGs + + + + Websites + + + + Pages is free + + + + Secure your website
Use any static website generator or plain HTMLCreate websites for your projects, groups, or user accountHost on GitLab.com for free, or on your own GitLab instanceConnect your custom domain(s) and TLS certificates
+ +Pages is available for free for all GitLab.com users as well as for self-managed +instances (GitLab Core, Starter, Premium, and Ultimate). + +## Overview + +
+
+

+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.

+

Pages does not support dynamic server-side processing, for instance, as .php and .asp requires. See this article to learn more about +static websites vs dynamic websites.

+
+
Examples of SSGs supported by Pages
+
+ +### 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**. + + + + + + + + + + + + + + + + +
Fork + + + + Deploy + + + + Visit
Fork an example projectDeploy your websiteVisit your website's URL
+ +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** +** 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://.gitlab.io/`. 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** +** 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/) -- cgit v1.2.1