Publishing to gitlab-pages

[tjaeggi]

Description

In your Documentation you publish a .gitlab-ci.yml like this:

pages:
  stage: deploy
  image: python:latest
  script:
    - pip install zensical
    - zensical build --clean 
  pages:
    publish: public
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

This creates a fatal error. With this correction publish: site, it works:

pages:
  stage: deploy
  image: python:latest
  script:
    - pip install zensical
    - zensical build --clean
  pages:
    publish: site
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

Related links

• Reporting a docs issue in
• Section: GitLab Pages

Proposed change

Correct it

Before submitting

• I have read and followed the documentation issue guidelines.
• I have attached the links to the affected sections of the documentation

[squidfunk]

Thanks for reporting. Things were changed in in #58. Maybe @carloseguevara can take a look, since he proposed the change? We're not users of GitLab ourselves.

[carloseguevara]

Absolutely, I can handle it!

@tjaeggi Could you please tell me what the fatal error message is?

[carloseguevara]

Maybe you missed the warning after that:

!!! warning "Prerequisites" Make sure to change site_dir to public in your configuration as GitLab requires this.

With this configuration, you change the build folder from "site" to "public" and make match with the default gitlab configuration.

In other words, if you put your gitlab code "pages: publish: site" you don't need to change the zensical configuration. In the documentation we change the zensical configuration to match with the default folder expected by gitlab, so you can use or "pages: true" (more simple but we assume "public" as default folder by gitlab) or "pages: publish: public" (more explicit to avoid posible changes in gitlab site).

[squidfunk]

Okay, so then I misunderstood your PR. I thought GitLab requires it to be public. It this is not the case, we should change it back to site, since this is the default.

[alexvoss]

It seems that we are at a bit of an impasse here. The Gitlab documentation explicitly says that the output needs to be in the public folder at the root level:

Your app must output files to the public folder.
(https://docs.gitlab.com/user/project/pages/getting_started/pages_ui/)

It even gives instructions for various SSGs to change the output folder.

At the same time, it seems like the folder can be configured in the .gitlab-ci.yml. The UI for setting up pages includes an option for specifying a custom folder. Does this mean we should ignore Gitlab's docs? It would simplify our own docs as we could remove the admonition to change the site_dir.

One other thing we could change, I think, is the Docker image used. Using the Zensical docker image would save us a pip install and to might speed up runs / make them more resource efficient. I think the instructions for Gitlab predate the Zensical Docker image.

[alexvoss]

Ok, I have slept on it and also found a statement from the Gitlab project that changing the site_dir is no longer necessary. They have hidden it in a details section (history, at the top), on their page about the public folder. The functionality was enabled on Gitlab itself in version 16.1 and for self-hosted in version 16.2. Both releases are from 2023.

I will PR a change now to remove the admonition and adjust the Gitlab config, adding a code admonition to clarify in case people are confused after reading the Gitlab docs. I think that is the cleanest solution.

[carloseguevara]

Just so you know, as I mentioned in my PR, we have a bit of a mix-up in the configuration here.

In this document, we ask the user to change the site_dir to public. So, if we ask them to do this, we should update the gitlab configuration to point to the public folder.

However, if we don’t change the project configuration to publish in the public folder instead of the site folder by default, then we don’t need to change the gitlab configuration because site is already the default folder.

The initial issue is likely because the user didn’t complete all the steps.

[carloseguevara]

So what’s the plan?

I was thinking we could stick with the default settings. To do that, we’ll need to take out both the project configuration (so it can be published in the site folder) and the gitlab configuration (so it can look for the site folder).

[alexvoss]

I have just created PR #96 to try and sort it out. Would have thought GitHub would display it here because I did mention the issue in its title.

[alexvoss]

Resolved with 40c0b64, closing. Thanks for your contributions. Feel free to re-open if you find that there is something I have not considered or otherwise managed to get wrong. I ran a test project on Gitlab but I am not a regular user.