How to render assets when building a static website with GitLab Pages and Jekyll

Question

I'm using Jekyll to build a static site and deploy it with GitLab Pages. This site is compounded of posts (contained in the site/_posts folder) and refer to other HTML and Markdown documents that I placed in an assets folder at the project's root, as recommended by Jekyll docs.

When I build the website in the pipeline it runs and deploys it successfully to GitLab Pages. However, if I am able to find my posts, the links towards the files allegedly contained in assets return a 404. When I browse the public artifacts file, I can't see said files in the assets folder, even though I put them there before building the site.

What am I missing here? It runs fine when serving locally but as soon as it is deployed on GitLab Pages I can't access the assets file.

project architecture:

site/
|__> _posts/
|____> entry.md
assets/
|__> v{{ version }}/
|____> yellow-ducky.html
|____> black-ducky.md

.gitlab-ci.yml excerpt:

pages:
  stage: deploy
  tags: [docker-connect]
  script:
    # entry.md is the blog post I want to publish
    - mv entry.md site/_posts/`date +'%Y-%m-%d'`-entry.md
    # reports come from a previous job's artifacts and contain all files I want to place in assets
    - mkdir -p assets assets/v${TAG}
    - mv reports/* assets/v${TAG}/
    # build website
    - gem install bundler
    - cd site
    - bundle install
    - bundle exec jekyll build -d public
    # move built files to the folder where GitLab expects to find them
    - cd .. && mkdir -p public && mv site/public/* public/
  artifacts:
    paths:
      - public

_config.yml excerpt:

title: RubberDucky
email: [email protected]
description: >- # this means to ignore newlines until "baseurl:"
  This is the place where to find all info you need about rubber ducks. 
baseurl: "/toys/rubberduck" # the subpath of your site, e.g. /blog
url: "https://gitlab.troubleshoot.io" # the base hostname & protocol for your site, e.g. http://example.com
# Build settings
theme: minima
plugins:
  - jekyll-feed

blog post excerpt:

<ul style="list-style-type:none">
    {% for duck in ducks %}
        <h2>{{ duck.name }}</h2>
        <li><a href="assets/v{{ version }}/{{ duck.url }}">View</a> | <a href="assets/v{{ version }}/{{ duck.url }}" download>Download</a></li>
    {% endfor %}
</ul>

Answer 1

It appears the issue is in the URL used to access the documents in the blog post excerpt. First of all, the URL should begin with a / since the assets folder is at the root of the site project. However (and most importantly), I also had to add the baseurl to the file URL as shown below:

blog post excerpt:

<ul style="list-style-type:none">
    {% for duck in ducks %}
        <h2>{{ duck.name }}</h2>
        <li><a href="/{{ baseurl }}/assets/v{{ version }}/{{ duck.url }}">View</a> | <a href="/{{ baseurl }}/assets/v{{ version }}/{{ duck.url }}" download>Download</a></li>
    {% endfor %}
</ul>

If I weren't building my post entries from a template the link would actually be /{{ site.baseurl }}/assets/v{{ version }}/{{ duck.url }}, but Jinja does not understand the site.baseurl object when rendering the template. To bypass this, I read the value of the predefined GitLab CI_PROJECT_PATH variable and pass it to the template under the name baseurl when rendering.