Skip to content

G
gitlab-ce
Commit adc5295f authored by Russell Dickenson's avatar Russell Dickenson
Browse files
Options

Merge branch 'selhorn-pages4' into 'master' 

Docs: More Pages work

See merge request gitlab-org/gitlab!33546
parents 66761ce5 cfdef5d9
Hide whitespace changes
Inline Side-by-side
Showing with 90 additions and 83 deletions
doc/user/project/pages/getting_started/fork_sample_project.md
View file @ adc5295f
......@@ -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
View file @ adc5295f
......@@ -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
View file @ adc5295f
......@@ -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
View file @ adc5295f
......@@ -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.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7