Versioning on Gitlab Pages

[hpsems]

Hi all,

im trying to set up versioning with gitlab pages following the documentation on:
Gitlab Pages
and
Versioning

When deploying a version with mike a new branch "gh-pages" is created wich contains folders with the deployed versions and aliases. Therefore i think that mike is working fine.

But my deployed docs dont show a version selector.
Also tried to replicate the example using Gitlab pages, but no luck.

Q:

• Do i need do make a change to my .gitlab-ci.yml when using versioning, that isnt mentioned by the docs?
• Has someone used the versioning feature with Gitlab pages and can give advice?

Any advice is immensely appreciated!

Thanks in advance.

[squidfunk]

I have no experience with GitLab, but you have to make sure that versions.json is loaded correctly. If it isn't, the version selector cannot be shown (and an error should be visible in the console). versions.json should be located at the root of your documentation:

The structure must be as follows (which mike automatically ensures, at least when deploying to GitHub):

http://example.com/versions.json
http://example.com/en/
http://example.com/de/
...

Otherwise, consider asking on the mike repository if there's support for GitLab.

[hpsems]

We found a workaround:

With mike deploy the content of the /site folder is pushed to a branch called gh-pages and placed into a folder according to the specified version. This works well for Github it seems (i believe Github Pages will publish everything on that branch).

Gitlab Pages however does not look for the site's content on a specific branch but in the /public folder, wich is why you specify it as the artifacts path. This of course works fine for docs without multiple versions. See Docs on Gitlab Pages

So what we did is create a Pipeline on the gh-pages branch, that just takes all the content on it and moves it to the public folder, where Gitlab will expect it:

image: python:latest
pages:
  stage: deploy
  only:
    - gh-pages
  script:
    - mkdir .public
    - cp -r * .public
    - mv .public public
    - ls
  artifacts:
    paths:
      - public

This works well for us, although it is quite a different concept since the site is no longer built by the Gitlab Runner as with the approach described in the docs, but on the local machine where you deploy your docs from via mike. (That seems to be the intended use of mike btw). This is something to be aware of.

Hope this may help anyone who has the same problem.

[hpsems]

Solved:

I've found a simple solution:
GitHub will automatically publish the gh-pages branch in the pages. But in GitLab we need to add a .gitlab-ci.yml file into the gh-pages branch to have the same effect. A simple example of that file could look like this:

image: python:latest
pages:
  stage: deploy
  only:
    - gh-pages
  script:
    - mkdir .public
    - cp -r * .public
    - mv .public public
  artifacts:
    paths:
      - public
  # if one uses the GitLab-Runner with tags:
  tags:
    - Documentation

With this file set in place the versioning example of @squidfunk will work fine on GitLab.