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
getzola · Dec 21, 2023 · 38199c1 · 38199c1
1 parent 623756e
commit 38199c1
Showing 1 changed file with 80 additions and 32 deletions.
diff --git a/docs/content/documentation/deployment/gitlab-pages.md b/docs/content/documentation/deployment/gitlab-pages.md
@@ -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.
+
+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.
 
-> Congratulations! Your pages are served under:  
-https://john.gitlab.io
+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 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/).
+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/).