Update the GitLab Pages documentation (#2384)
* docs: update gitlab-pages.md * docs: rephrase sentence * docs: add clarification * docs: fix formatting * docs: add link to gitlab docs * docs: update gitlab-pages-md * docs: refactor gitlab-pages.md
This commit is contained in:
Javier Pérez
GitHub
parent
623756e7e3
commit
38199c1255
@ -3,68 +3,116 @@ title = "GitLab Pages"
|
||||
weight = 40
|
||||
+++
|
||||
|
||||
We are going to use the GitLab CI runner to automatically publish the site (this CI runner is already included in your repository if you use GitLab.com).
|
||||
We are going to use the GitLab Runner in GitLab CI/CD to host
|
||||
the site on GitLab Pages.
|
||||
|
||||
## Repository setup
|
||||
## Configuring your repository
|
||||
|
||||
Your repository needs to be set up to be a user or group website. This means the name of the repository has to be in the correct format.
|
||||
It is possible to host your Zola site on either the SaaS instance offered by
|
||||
GitLab (<https://gitlab.com>) or on a self-hosted instance.
|
||||
|
||||
For example, assuming that the username is `john`, you have to create a project called `john.gitlab.io`. Your project URL will be `https://gitlab.com/john/john.gitlab.io`. Once you enable GitLab Pages for your project, your website will be published under `https://john.gitlab.io`.
|
||||
It is recommended to create a repository on GitLab that contains solely your
|
||||
Zola project. The [Zola's directory structure](https://www.getzola.org/documentation/getting-started/directory-structure/)
|
||||
should be located in the root directory of your repository.
|
||||
|
||||
Under your group `websites`, you created a project called `websites.gitlab.io`. Your project’s URL will be `https://gitlab.com/websites/websites.gitlab.io`. Once you enable GitLab Pages for your project, your website will be published under `https://websites.gitlab.io`.
|
||||
For information on how to create and manage a repository on GitLab, refer to:
|
||||
|
||||
<https://docs.gitlab.com/ee/user/project/repository/>
|
||||
|
||||
This guide assumes that your Zola project is located in the root of your repository.
|
||||
## Ensuring that the runner can access your theme
|
||||
|
||||
## Ensuring that the CI runner can access your theme
|
||||
|
||||
Depending on how you added your theme, your repository may not contain it. The best way to ensure that the theme will
|
||||
be added is to use submodules. When doing this, ensure that you are using the `https` version of the URL.
|
||||
Depending on how you added your theme, your repository may not contain it.
|
||||
The best way to ensure that the theme will be added is to use submodules.
|
||||
When doing this, ensure that you are using the `https` version of the URL.
|
||||
|
||||
```bash
|
||||
$ git submodule add {THEME_URL} themes/{THEME_NAME}
|
||||
git submodule add {THEME_URL} themes/{THEME_NAME}
|
||||
```
|
||||
|
||||
For example, this could look like:
|
||||
|
||||
```bash
|
||||
$ git submodule add https://github.com/getzola/hyde.git themes/hyde
|
||||
git submodule add https://github.com/getzola/hyde.git themes/hyde
|
||||
```
|
||||
|
||||
## Setting up the GitLab CI/CD Runner
|
||||
## Setting up the GitLab Runner
|
||||
|
||||
The second step is to tell the GitLab continuous integration runner how to create the GitLab page.
|
||||
The GitLab Runner needs to know how to create your site in order to deploy
|
||||
it to the GitLab Pages server.
|
||||
|
||||
To do this, create a file called `.gitlab-ci.yml` in the root directory of your repository.
|
||||
We provide you with a template to accomplish this task easily.
|
||||
Create a file called `.gitlab-ci.yml` in the root directory of your
|
||||
repository and copy the contents of the template below.
|
||||
|
||||
```yaml
|
||||
image: alpine:latest
|
||||
stages:
|
||||
- deploy
|
||||
|
||||
default:
|
||||
image: debian:stable-slim
|
||||
tags:
|
||||
- docker
|
||||
|
||||
variables:
|
||||
# This variable will ensure that the CI runner pulls in your theme from the submodule
|
||||
GIT_SUBMODULE_STRATEGY: recursive
|
||||
# The runner will be able to pull your Zola theme when the strategy is
|
||||
# set to "recursive".
|
||||
GIT_SUBMODULE_STRATEGY: "recursive"
|
||||
|
||||
# If you don't set a version here, your site will be built with the latest
|
||||
# version of Zola available in GitHub releases.
|
||||
# Use the semver (x.y.z) format to specify a version. For example: "0.17.2" or "0.18.0".
|
||||
ZOLA_VERSION:
|
||||
description: "The version of Zola used to build the site."
|
||||
value: ""
|
||||
|
||||
pages:
|
||||
stage: deploy
|
||||
script:
|
||||
# Install the zola package from the alpine community repositories
|
||||
- apk add --update-cache --repository http://dl-cdn.alpinelinux.org/alpine/edge/community/ zola
|
||||
# Execute zola build
|
||||
- zola build
|
||||
- |
|
||||
apt-get update --assume-yes && apt-get install --assume-yes --no-install-recommends wget ca-certificates
|
||||
if [ $ZOLA_VERSION ]; then
|
||||
zola_url="https://github.com/getzola/zola/releases/download/v$ZOLA_VERSION/zola-v$ZOLA_VERSION-x86_64-unknown-linux-gnu.tar.gz"
|
||||
if ! wget --quiet --spider $zola_url; then
|
||||
echo "A Zola release with the specified version could not be found.";
|
||||
exit 1;
|
||||
fi
|
||||
else
|
||||
github_api_url="https://api.github.com/repos/getzola/zola/releases/latest"
|
||||
zola_url=$(
|
||||
wget --output-document - $github_api_url |
|
||||
grep "browser_download_url.*linux-gnu.tar.gz" |
|
||||
cut --delimiter : --fields 2,3 |
|
||||
tr --delete "\" "
|
||||
)
|
||||
fi
|
||||
wget $zola_url
|
||||
tar -xzf *.tar.gz
|
||||
./zola build
|
||||
|
||||
artifacts:
|
||||
paths:
|
||||
# Path of our artifacts
|
||||
# This is the directory whose contents will be deployed to the GitLab Pages
|
||||
# server.
|
||||
# GitLab Pages expects a directory with this name by default.
|
||||
- public
|
||||
|
||||
# This config will only publish changes that are pushed on the main branch
|
||||
only:
|
||||
- main
|
||||
rules:
|
||||
# This rule makes it so that your website is published and updated only when
|
||||
# you push to the default branch of your repository (e.g. "master" or "main").
|
||||
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
|
||||
```
|
||||
|
||||
Push this new file and ... Tada! You're done! If you navigate to `settings > pages`, you should be able to see
|
||||
something like this:
|
||||
Please, keep in mind that this template assumes you are using the
|
||||
[Docker executor](https://docs.gitlab.com/runner/executors/docker.html)
|
||||
on your GitLab Runner.
|
||||
Feel free to adjust the file to your workflow and specific requirements.
|
||||
|
||||
> Congratulations! Your pages are served under:
|
||||
https://john.gitlab.io
|
||||
After you push this file to the default branch of your repository
|
||||
(e.g. "master" or "main"), your site will be ready. The GitLab CI/CD pipelines
|
||||
will ensure your site is published and updated automatically.
|
||||
|
||||
More information on the process to host on GitLab pages and additional information like using a custom domain is documented
|
||||
[in this GitLab blog post](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/).
|
||||
On the left sidebar of GitLab, navigate to **Deploy > Pages** to find the URL of your
|
||||
website inside the **Access pages** section.
|
||||
|
||||
More information on how to host your site on GitLab Pages is available
|
||||
[in the official GitLab documentation](https://docs.gitlab.com/ee/user/project/pages/).
|
||||
|
||||
Loading…
Reference in New Issue
Block a user