reivilibre/mirror-zola
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Update the GitLab Pages documentation (#2384)

Browse Source 
* 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 2023-12-21 12:34:16 +01:00 committed by GitHub
parent 623756e7e3
commit 38199c1255
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 80 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

112
docs/content/documentation/deployment/gitlab-pages.md
View File

@ -3,68 +3,116 @@ title = "GitLab Pages"
weight = 40 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.
Depending on how you added your theme, your repository may not contain it. The best way to ensure that the theme will When doing this, ensure that you are using the `https` version of the URL.
be added is to use submodules. When doing this, ensure that you are using the `https` version of the URL.
```bash ```bash
$ git submodule add {THEME_URL} themes/{THEME_NAME} git submodule add {THEME_URL} themes/{THEME_NAME}
``` ```
For example, this could look like: For example, this could look like:
```bash ```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 ```yaml
image: alpine:latest stages:
- deploy
default:
image: debian:stable-slim
tags:
- docker
variables: variables:
# This variable will ensure that the CI runner pulls in your theme from the submodule # The runner will be able to pull your Zola theme when the strategy is
GIT_SUBMODULE_STRATEGY: recursive # 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: pages:
stage: deploy
script: script:
# Install the zola package from the alpine community repositories - |
- apk add --update-cache --repository http://dl-cdn.alpinelinux.org/alpine/edge/community/ zola apt-get update --assume-yes && apt-get install --assume-yes --no-install-recommends wget ca-certificates
# Execute zola build if [ $ZOLA_VERSION ]; then
- zola build 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: artifacts:
paths: 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 - public
# This config will only publish changes that are pushed on the main branch rules:
only: # This rule makes it so that your website is published and updated only when
- main # 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 Please, keep in mind that this template assumes you are using the
something like this: [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: After you push this file to the default branch of your repository
https://john.gitlab.io (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 On the left sidebar of GitLab, navigate to **Deploy > Pages** to find the URL of your
[in this GitLab blog post](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/). 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/).