diff options
Diffstat (limited to 'doc/user/project/pages')
12 files changed, 115 insertions, 133 deletions
diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md index 1d32091b294..197524f2fc5 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/dns_concepts.md @@ -35,7 +35,7 @@ for the most popular hosting services: - [123-reg](https://www.123-reg.co.uk/support/domains/domain-name-server-dns-management-guide/) - [Amazon](https://docs.aws.amazon.com/AmazonS3/latest/dev/website-hosting-custom-domain-walkthrough.html) - [Bluehost](https://www.bluehost.com/help/article/dns-management-add-edit-or-delete-dns-entries) -- [Cloudflare](https://support.cloudflare.com/hc/en-us/articles/201720164-Creating-a-Cloudflare-account-and-adding-a-website) +- [Cloudflare](https://developers.cloudflare.com/fundamentals/get-started/setup/) - [cPanel](https://documentation.cpanel.net/display/84Docs/Edit+DNS+Zone) - [DigitalOcean](https://docs.digitalocean.com/products/networking/dns/how-to/manage-records/) - [DreamHost](https://help.dreamhost.com/hc/en-us/articles/360035516812) diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/img/add_certificate_to_pages.png b/doc/user/project/pages/custom_domains_ssl_tls_certification/img/add_certificate_to_pages.png Binary files differdeleted file mode 100644 index d92a981dc60..00000000000 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/img/add_certificate_to_pages.png +++ /dev/null diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md index 6378d962ffe..dc23540bd1b 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -52,15 +52,14 @@ this document for an [overview on DNS records](dns_concepts.md). #### 1. Add a custom domain -Navigate to your project's **Setting > Pages** and select **+ New domain** -to add your custom domain to GitLab Pages. You can choose whether to: +To add your custom domain to GitLab Pages: -- Add an [SSL/TLS certificate](#adding-an-ssltls-certificate-to-pages). -- Leave it blank (it can be added later). - -Select **Create New Domain**. - - +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Pages**. +1. In the top right, select **New Domain**. +1. In **Domain**, enter your domain. +1. Optional. In **Certificate**, turn off the **Automatic certificate management using Let's Encrypt** toggle to add an [SSL/TLS certificate](#adding-an-ssltls-certificate-to-pages). You can also add the certificate and key later. +1. Select **Create New Domain**. #### 2. Get the verification code @@ -292,8 +291,6 @@ meet these requirements. - To add the certificate to a domain previously added, go to your project's **Settings > Pages**, locate your domain name, select **Details** and **Edit** to add the certificate. - - 1. Add the PEM certificate to its corresponding field. 1. If your certificate is missing its intermediate, copy and paste the root certificate (usually available from your CA website) diff --git a/doc/user/project/pages/getting_started/pages_ci_cd_template.md b/doc/user/project/pages/getting_started/pages_ci_cd_template.md index caf98e8a8a4..339ab239588 100644 --- a/doc/user/project/pages/getting_started/pages_ci_cd_template.md +++ b/doc/user/project/pages/getting_started/pages_ci_cd_template.md @@ -26,13 +26,12 @@ these steps, you may have to do additional configuration for the Pages site to g If everything is configured correctly, the site can take approximately 30 minutes to deploy. -You can watch the pipeline run by navigating to **CI/CD > Pipelines**. +To view the pipeline, go to **CI/CD > Pipelines**. When the pipeline is finished, go to **Settings > Pages** to find the link to your Pages website. -To view the HTML and other assets that were created for the site, -go to the **Pipelines** tab, view the job, and on the right side, -select **Download artifacts**. - For every change pushed to your repository, GitLab CI/CD runs a new pipeline that immediately publishes your changes to the Pages site. + +To view the HTML and other assets that were created for the site, +[download the job artifacts](../../../../ci/pipelines/job_artifacts.md#download-job-artifacts). diff --git a/doc/user/project/pages/getting_started/pages_forked_sample_project.md b/doc/user/project/pages/getting_started/pages_forked_sample_project.md index 69c60cab4b3..9841e52a089 100644 --- a/doc/user/project/pages/getting_started/pages_forked_sample_project.md +++ b/doc/user/project/pages/getting_started/pages_forked_sample_project.md @@ -29,32 +29,37 @@ When the pipeline is finished, go to **Settings > Pages** to find the link to yo For every change pushed to your repository, GitLab CI/CD runs a new pipeline that immediately publishes your changes to the Pages site. -To view the HTMl and other assets that were created for the site, -go to the **Pipelines** tab, view the job, and on the right side, -select **Download artifacts**. +## Remove the fork relationship -You can take some **optional** further steps: +If you want to contribute to the project you forked from, +you can keep the forked relationship. Otherwise: -- Remove the fork relationship. If you want to contribute to the project you forked from, - you can keep this relationship. Otherwise, go to your project's **Settings > General**, - expand **Advanced settings**, and scroll down to **Remove fork relationship**: +1. On the left sidebar, select **Settings > General**. +1. Expand **Advanced settings**. +1. Select **Remove fork relationship**. -  +## Change the URL -- Change the URL to match your namespace. If your Pages site is hosted on GitLab.com, - you can rename it to `<namespace>.gitlab.io`, where `<namespace>` is your GitLab namespace - (the one you chose when you forked the project). +You can change the URL to match your namespace. +If your Pages site is hosted on GitLab.com, +you can rename it to `<namespace>.gitlab.io`, where `<namespace>` is your GitLab namespace +(the one you chose when you forked the project). - - Go to your project's **Settings > General** and expand **Advanced**. Scroll down to - **Change path** and change the path to `<namespace>.gitlab.io`. +1. On the left sidebar, select **Settings > General**. +1. Expand **Advanced**. +1. In **Change path**, update the path to `<namespace>.gitlab.io`. - For example, if your project's URL is `gitlab.com/gitlab-tests/jekyll`, your namespace is - `gitlab-tests`. + For example, if your project's URL is `gitlab.com/gitlab-tests/jekyll`, your namespace is + `gitlab-tests`. - If you set the repository path to `gitlab-tests.gitlab.io`, - the resulting URL for your Pages website is `https://gitlab-tests.gitlab.io`. + If you set the repository path to `gitlab-tests.gitlab.io`, + the resulting URL for your Pages website is `https://gitlab-tests.gitlab.io`. -  +  - - Now go to your SSG's configuration file and change the [base URL](../getting_started_part_one.md#urls-and-base-urls) - from `"project-name"` to `""`. The project name setting varies by SSG and may not be in the configuration file. +1. Open your SSG configuration file and change the [base URL](../getting_started_part_one.md#urls-and-base-urls) + from `"project-name"` to `""`. The project name setting varies by SSG and may not be in the configuration file. + +## Related topics + +- [Download the job artifacts](../../../../ci/pipelines/job_artifacts.md#download-job-artifacts) diff --git a/doc/user/project/pages/getting_started/pages_from_scratch.md b/doc/user/project/pages/getting_started/pages_from_scratch.md index c0a1e8f16e0..ebadf39a984 100644 --- a/doc/user/project/pages/getting_started/pages_from_scratch.md +++ b/doc/user/project/pages/getting_started/pages_from_scratch.md @@ -420,9 +420,8 @@ Now GitLab CI/CD not only builds the website, but also: - **Caches** dependencies installed with Bundler. - **Continuously deploys** every push to the `main` branch. -To view the HTMl and other assets that were created for the site, -go to the **Pipelines** tab, view the job, and on the right side, -select **Download artifacts**. +To view the HTML and other assets that were created for the site, +[download the job artifacts](../../../../ci/pipelines/job_artifacts.md#download-job-artifacts). ## Related topics diff --git a/doc/user/project/pages/getting_started/pages_new_project_template.md b/doc/user/project/pages/getting_started/pages_new_project_template.md index e4890954d13..a0f9753a40c 100644 --- a/doc/user/project/pages/getting_started/pages_new_project_template.md +++ b/doc/user/project/pages/getting_started/pages_new_project_template.md @@ -29,6 +29,5 @@ 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. -To view the HTMl and other assets that were created for the site, -go to the **Pipelines** tab, view the job, and on the right side, -select **Download artifacts**. +To view the HTML and other assets that were created for the site, +[download the job artifacts](../../../../ci/pipelines/job_artifacts.md#download-job-artifacts). diff --git a/doc/user/project/pages/getting_started/pages_ui.md b/doc/user/project/pages/getting_started/pages_ui.md index ba97fcb8749..a6069b473e6 100644 --- a/doc/user/project/pages/getting_started/pages_ui.md +++ b/doc/user/project/pages/getting_started/pages_ui.md @@ -4,59 +4,69 @@ group: Incubation info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Tutorial: Use the GitLab UI to deploy your static site **(FREE)** +# Create a Pages deployment for your static site **(FREE)** -This tutorial assumes you have a project that either: +If you already have a GitLab project that contains your static site or framework, +you can generate a GitLab Pages website from it. -- Generates static sites or a client-rendered single-page application (SPA), - such as [Eleventy](https://www.11ty.dev), [Astro](https://astro.build), or [Jekyll](https://jekyllrb.com). -- Contains a framework configured for static output, such as [Next.js](https://nextjs.org), - [Nuxt.js](https://nuxtjs.org), or [SvelteKit](https://kit.svelte.dev). +When you provide basic information in the UI, a `.gitlab-ci.yml` file is created +and a merge request opened. When you commit the merge request, +a pipeline deploys your Pages website. -## Update your app to output files to the `public` folder +## Prerequisites -GitLab Pages requires all files intended to be part of the published website to -be in a root-level folder called `public`. If you create this folder during the build -pipeline, committing it to Git is not required. +- Your app must [output files to the `public` folder](../public_folder.md). If you create + this folder during the build pipeline, you do not need to commit it to Git. -For detailed instructions, read [Configure the public files folder](../public_folder.md). + WARNING: + This step is important. Ensure your files are in a root-level `public` folder. -## Set up the `.gitlab-ci.yml` file +- You must have a project that either: + - Generates static sites or a client-rendered single-page application (SPA), + like [Eleventy](https://www.11ty.dev), [Astro](https://astro.build), or [Jekyll](https://jekyllrb.com). + - Contains a framework configured for static output, such as [Next.js](https://nextjs.org), + [Nuxt.js](https://nuxtjs.org), or [SvelteKit](https://kit.svelte.dev). +- GitLab Pages must be enabled for the project. (To enable, go to **Settings > General**, + expand **Visibility, project features, permissions**, and turn on the **Pages** toggle.) -GitLab helps you write the `.gitlab-ci.yml` needed to create your first GitLab Pages -deployment pipeline. Rather than building the file from scratch, it asks you to -provide the build commands, and creates the necessary boilerplate for you. +## Create the Pages deployment -To build your YAML file from the GitLab UI: +To complete the setup and generate a GitLab Pages deployment: 1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Pages** to display the friendly - interface **Get Started With Pages**. -1. If your framework's build process does not need one of the provided build - commands, you can either: +1. On the left sidebar, select **Settings > Pages**. A **Get Started with Pages** form appears. + If this form is not available, see [Troubleshooting](#if-the-get-started-with-pages-form-is-not-available). +1. For **Step 1**, enter an image name and verify that your files are in a `public` folder. +1. Select **Next**. +1. For **Step 2**, enter your installation steps. If your framework's build process does not + need one of the provided build commands, you can either: - Skip the step by selecting **Next**. - Enter `:` (the bash "do nothing" command) if you still want to incorporate that step's boilerplate into your `.gitlab-ci.yml` file. -1. Optional. Edit and adjust the generated `.gitlab-ci.yml` file as needed. -1. Commit your `.gitlab-ci.yml` to your repository. This commit triggers your first +1. Select **Next**. +1. For **Step 3**, enter scripts that indicate how to build your application. +1. Select **Next**. +1. Optional. Edit the generated `.gitlab-ci.yml` file as needed. +1. For **Step 4**, add a commit message and select **Commit**. This commit triggers your first GitLab Pages deployment. -To view the HTMl and other assets that were created for the site, -go to **CI/CD > Pipelines**, view the job, and on the right side, -select **Download artifacts**. +To view the running pipeline, go to **CI/CD > Pipelines**. + +To view the artifacts that were created during the deployment, view the job, +and on the right side, select **Download artifacts**. ## Troubleshooting -### If you can't see the "Get Started with Pages" interface +### If the `Get Started with Pages` form is not available -GitLab doesn't show this interface if you have either: +When you go to **Settings > Pages**, the form is not available if you: - Deployed a GitLab Pages site before. -- Committed a `.gitlab-ci.yml` through this interface at least once. +- Committed a `.gitlab-ci.yml` through the forms at least one time. -To fix this problem: +To fix this issue: -- If you see the message **Waiting for the Pages Pipeline to complete**, select - **Start over** to start the wizard again. +- If the message **Waiting for the Pages Pipeline to complete** appears, select + **Start over** to start the form again. - If your project has previously deployed GitLab Pages successfully, - [manually update](pages_from_scratch.md) your `.gitlab-ci.yml`. + [manually update](pages_from_scratch.md) your `.gitlab-ci.yml` file. diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 588d94729e2..a0c8073d6eb 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -87,7 +87,7 @@ Every Static Site Generator (SSG) default configuration expects to find your website under a (sub)domain (`example.com`), not in a subdirectory of that domain (`example.com/subdir`). Therefore, whenever you publish a project website (`namespace.gitlab.io/project-name`), -you must look for this configuration (base URL) on your SSG's +you must look for this configuration (base URL) on your static site generator's documentation and set it up to reflect this pattern. For example, for a Jekyll site, the `baseurl` is defined in the Jekyll diff --git a/doc/user/project/pages/img/remove_fork_relationship_v13_1.png b/doc/user/project/pages/img/remove_fork_relationship_v13_1.png Binary files differdeleted file mode 100644 index 84aa2e571c7..00000000000 --- a/doc/user/project/pages/img/remove_fork_relationship_v13_1.png +++ /dev/null diff --git a/doc/user/project/pages/public_folder.md b/doc/user/project/pages/public_folder.md index a19e296b954..8c9f1cbec86 100644 --- a/doc/user/project/pages/public_folder.md +++ b/doc/user/project/pages/public_folder.md @@ -2,40 +2,39 @@ description: 'Learn how to configure the build output folder for the most common static site generators' stage: Create -group: Incubation +group: Editor info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Configure the public files folder **(FREE)** -GitLab Pages requires all files you intend to be available in the published website to -be in a root-level folder called `public`. This page describe how -to set this up for some common static site generators. +All the files that should be accessible by the browser must be in a root-level folder called `public`. -## Guide by framework +Follow these instructions to configure the `public` folder +for the following frameworks. -### Eleventy +## Eleventy -For Eleventy, you should either: +For Eleventy, you should do one of the following: -1. Add the `--output=public` flag in Eleventy's build commands, for example: +- Add the `--output=public` flag in Eleventy's build commands, for example: - `npx @11ty/eleventy --input=path/to/sourcefiles --output=public` + `npx @11ty/eleventy --input=path/to/sourcefiles --output=public` -1. Add the following to your `.eleventy.js` file: +- Add the following to your `.eleventy.js` file: - ```javascript - // .eleventy.js - module.exports = function(eleventyConfig) { - return { - dir: { - output: "public" - } - } - }; - ``` + ```javascript + // .eleventy.js + module.exports = function(eleventyConfig) { + return { + dir: { + output: "public" + } + } + }; + ``` -### Astro +## Astro By default, Astro uses the `public` folder to store static assets. For GitLab Pages, rename that folder to a collision-free alternative first: @@ -65,11 +64,11 @@ rename that folder to a collision-free alternative first: }); ``` -### SvelteKit +## SvelteKit NOTE: GitLab Pages supports only static sites. For SvelteKit, -we recommend using [`adapter-static`](https://kit.svelte.dev/docs/adapters#supported-environments-static-sites). +you can use [`adapter-static`](https://kit.svelte.dev/docs/adapters#supported-environments-static-sites). When using `adapter-static`, add the following to your `svelte.config.js`: @@ -86,11 +85,11 @@ export default { }; ``` -### Next.js +## Next.js NOTE: -GitLab Pages supports only static sites. For Next.js, we -recommend using Next's [Static HTML export functionality](https://nextjs.org/docs/advanced-features/static-html-export) +GitLab Pages supports only static sites. For Next.js, you can use +Next's [Static HTML export functionality](https://nextjs.org/docs/advanced-features/static-html-export). Use the `-o public` flag after `next export` as the build command, for example: @@ -118,7 +117,7 @@ GitLab Pages supports only static sites. 1. Configure your Nuxt.js application for [Static Site Generation](https://nuxtjs.org/docs/features/deployment-targets/#static-hosting). -### Vite +## Vite Update your `vite.config.js` to include the following: @@ -131,7 +130,7 @@ export default { } ``` -### Webpack +## Webpack Update your `webpack.config.js` to include the following: @@ -147,9 +146,9 @@ module.exports = { ## Should you commit the `public` folder? Not necessarily. However, when the GitLab Pages deploy pipeline runs, it looks -for an [artifact](../../../ci/pipelines/job_artifacts.md) of that name. So +for an [artifact](../../../ci/pipelines/job_artifacts.md) of that name. If you set up a job that creates the `public` folder before deploy, such as by running `npm run build`, committing the folder isn't required. If you prefer to build your site locally, you can commit the `public` folder and -omit the build step during the job, instead. +omit the build step during the job instead. diff --git a/doc/user/project/pages/redirects.md b/doc/user/project/pages/redirects.md index 96de457c7f7..cf0c0dbff82 100644 --- a/doc/user/project/pages/redirects.md +++ b/doc/user/project/pages/redirects.md @@ -108,9 +108,8 @@ and an [HTTP status code](#http-status-codes): ## Rewrites -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/458) in GitLab 14.3. -> - Enabled on GitLab.com. -> - Disabled by default in self-managed GitLab behind the [`FF_ENABLE_PLACEHOLDERS` feature flag](#feature-flag-for-rewrites). +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/458) in GitLab 14.3 [with a flag](../../../administration/feature_flags.md) named `FF_ENABLE_PLACEHOLDERS`. Disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/619) in GitLab 15.2. Provide a status code of `200` to serve the content of the `to` path when the request matches the `from`: @@ -267,28 +266,3 @@ However, there are some minor differences: - Netlify redirects to `/new/:placeholder` (with a literal `:placeholder`). - GitLab redirects to `/new/`. - -## Feature flag for rewrites - -FLAG: -Rewrites in GitLab Pages is under development, and is deployed behind a feature flag -that is **disabled by default**. - -To enable rewrites, for [Omnibus installations](../../../administration/pages/index.md), define the -`FF_ENABLE_PLACEHOLDERS` environment variable in the -[global settings](../../../administration/pages/index.md#global-settings). -Add the following line to `/etc/gitlab/gitlab.rb` and -[reconfigure the instance](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure): - -```ruby -gitlab_pages['env']['FF_ENABLE_PLACEHOLDERS'] = 'true' -``` - -For [source installations](../../../administration/pages/source.md), define the -`FF_ENABLE_PLACEHOLDERS` environment variable, then -[restart GitLab](../../../administration/restart_gitlab.md#installations-from-source): - -```shell -export FF_ENABLE_PLACEHOLDERS="true" -/path/to/pages/bin/gitlab-pages -config gitlab-pages.conf -``` |
