Relative paths to icons in CI/CD environment

[NikosAlexandris]

Hello. When I build some documentation locally, it all works fine and I can see for example diagrams generated within executable code blocks (using https://pawamoy.github.io/markdown-exec/) and make use of custom icons/logos, rendered properly. When the same build process runs via a CI/CD in a GitLab, the diagrams fail to build/render simply because the icons/logs are not in the right directory.

I am lost as to where does the change of the root directory of all files related to the documentation are copied! I have locally my files under docs/icons and I use then inside some Markdown file (e.g. under/in docs/icons/source_code/architecture.md) like custom_icon = ../icons/some_icon.png. In the CI/CD container these are copied and available under the /` path, for example :

Locally

- docs
  - icons
  - source_code
    - architecture.md

CI

- .
- icons
- source_code
  - architecture.md

So, if an image is set to be found under ../icons/some_icon.png why does this relative path not work in the CI ?
What should I take care to do in order to get relative paths work ?
Is any bit from the configuration file relevant ?

ps- I 've seen a couple of issues mentioning relative paths, but I am still a bit lost on this.

[alexvoss]

I am not sure why the paths are different on the CI system? Note that MkDocs only copies files to site that reside under docs. That is why all assets should really by in that directory. That is, the problem is not the relative path but probably that the images are not being copied.

[NikosAlexandris]

I am not sure why the paths are different on the CI system? Note that MkDocs only copies files to site that reside under docs. That is why all assets should really by in that directory. That is, the problem is not the relative path but probably that the images are not being copied.

The icons/logos are copied, I cross-checked. Perhaps we (I or colleagues) have set-up the copy of stuff to the CI container wrongly!

We use currently in a Dockerfile that builds the relevant image :

..

# Install dependencies and configure locale/s as root
USER 0
RUN apt-get update \
    && apt-get install -y locales \
    && echo "LC_ALL=en_US.UTF-8" >> /etc/environment \
    && echo "en_US.UTF-8 UTF-8" >> /etc/locale.gen \
    && echo "LANG=en_US.UTF-8" >> /etc/locale.conf \
    && locale-gen en_US.UTF-8 \
    && dpkg-reconfigure --frontend=noninteractive locales \
    && update-locale LANG=en_US.UTF-8 \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

..

# Set environment variables after locales are configured
ENV LANG=en_US.UTF-8 \
    LC_ALL=en_US.UTF-8 \
    FORCE_COLOR=1 \
    PATH="/home/someuser/.local/bin:${PATH}"
    # ENV COLUMNS=160

WORKDIR /home/someuser/documentation
COPY --chown=someuser:someuser . .
RUN pip install --upgrade pip \
    && pip install --user pdm  \
    && pip install .[docs] \  
    && pdm install \
    && pdm run mkdocs build --verbose --site-dir public \
    && pip cache purge

..

# Copy the built project from the build stage
COPY --from=build /home/someuser/documentation/public /opt/app-root/src

..

[kamilkrzyskow]

The file tree example is different than the written path docs/icons/source_code/architecture.md. Probably a sort of typo, but worth pointing out.

When people have issues with relative paths they are typically related to the use_directory_urls mode which adds / at the end of the URLs instead of .html, this adds another layer in the file tree, so the generated HTML has 1 more ../ in the relative paths. This conversion from the filesystem relative paths to the web based ones is handled automatically via the MkDocs (only if the files are detected in the build process).

Also are the icons loaded via the "natural" means via Markdown/HTML or are they loaded in your Python code examples?
Perhaps the issue comes from the pyodide.js

Can you share some logs? I expect there is a 404 in your browser dev tools due to a lacking file, due to an incorrect URL, can you confirm that you can change the URL and properly fetch the image manually?

[NikosAlexandris]

The file tree example is different than the written path docs/icons/source_code/architecture.md. Probably a sort of typo, but worth pointing out.

Thanks. How so ?

icons and source_code are two directories at the same level, both under docs. Does it appear otherwise for you ?

When people have issues with relative paths they are typically related to the use_directory_urls mode which adds / at the end of the URLs instead of .html, this adds another layer in the file tree, so the generated HTML has 1 more ../ in the relative paths. This conversion from the filesystem relative paths to the web based ones is handled automatically via the MkDocs (only if the files are detected in the build process).

Also are the icons loaded via the "natural" means via Markdown/HTML or are they loaded in your Python code examples? Perhaps the issue comes from the pyodide.js

Indeed, they are loaded in the Python code, for example the architecture contains :

```python exec="true" html="true"
--8<-- "docs/source_code/architecture_diagram.py"
```

which in turn executes something like

from base64 import b64encode
from contextlib import suppress
from diagrams import Diagram, Edge, Cluster
from diagrams.custom import Custom
from diagrams.programming.language import Python
from diagrams.programming.framework import FastAPI


user_icon = "docs/icons/noun-user-6616649.svg"
try:
    with suppress(FileNotFoundError):
        graph_attr = {"splines":"spline"}
        with Diagram("prototype", direction="TB", show=False, graph_attr=graph_attr) as diagram:
            diagram.render = lambda: None
            User = Custom("User", user_icon)
            png = b64encode(diagram.dot.pipe(format="png")).decode()
    print(f'<img src="data:image/png;base64, {png}"/>')
except Exception as e:
    print(f"An error occurred: {e}")

Can you share some logs? I expect there is a 404 in your browser dev tools due to a lacking file, due to an incorrect URL, can you confirm that you can change the URL and properly fetch the image manually?

Will check more the logs -- though I have. Indeed and however : the architecture.md page is served for example under :

https://some-path/source_code/architecture/

while the icon is then available at

https://some-path/icons/noun-user-6616649.svg

The failure reads :

An error occured: the 'png' file is not defined

which is sort of a standard error response when diagrams can't find an icon.

Through the web-dev-inspect-etc tools I can obviously see (some) 404 error(s) -- some related to Google fonts and mathjax.
It seems its a rather simple fix, to get to understand what path should I use to point to the icons so the documentation builds correctly both locally and remotely.

[kamilkrzyskow]

Thanks. How so ?

docs/icons/source_code/architecture.md This path shows that the source_code is inside icons, and they're not on the same level.
So like I assumed, just a typo.

icons and source_code are two directories at the same level, both under docs. Does it appear otherwise for you ?

Based on the file tree code block example, this is what I assumed, thanks for the confirmation.

---

As for your other examples, where are the relative paths? 🤔

The snippets extension doesn't take MkDocs into account. The paths are always relative to your current working directory/pwd, aka, where you run pdm run mkdocs build --verbose --site-dir public, so if that path doesn't contain docs then --8<-- "docs/source_code/architecture_diagram.py" won't load the snippet. Unless you've modified the base_path option.

Second example, as it's written in Python, I guess it also works just like snippets, it expects the docs directory to exist
user_icon = "docs/icons/noun-user-6616649.svg", also I find the with suppress(FileNotFoundError): rather funny, as imo Custom should crash due to a missing icon, but I guess the suppress ignores the error?

---

Will check more the logs -- though I have. Indeed and however : the architecture.md page is served for example under :

https://some-path/source_code/architecture/

So as you're using the directory path ending with a / then the relative path in the rendered HTML needs to have one more ../ to escape the top level directory. I don't know what your Custom class does with the user_icon path, but worth keeping that in mind.

---

An error occured: the 'png' file is not defined

So despite suppressing the FileNotFoundError you still get some log warning hmm, I would prefer a full build crash with traceback over a log like this tbh 😁 Anyways, I would add more print debug statements to see what file path is being loaded.

Also where is that log? In your build or on the rendered page? I think it's the latter, so perhaps adding log statements isn't an option.

Through the web-dev-inspect-etc tools I can obviously see (some) 404 error(s) -- some related to Google fonts and mathjax.
It seems its a rather simple fix, to get to understand what path should I use to point to the icons so the documentation builds correctly both locally and remotely.

Since your script is executed via pyoide.js from markdown-exec and it loads the icons/diagrams then I guess there should be a way to make it log in a more verbose way in the dev-tools 🤔
Perhaps it's time to move the issue upstream to the plugin or ping the author to come here ✌️