Images are not shown in lab documents (.adoc files) in github

[jackhu008]

Issue: Images are not displayed in lab documents, for example, in /labs/tekton.adoc or /labs/servicemesh.adoc.

Cause: .adoc files expect images in the same folder in "/labs/" but images are actually located in a subfolder "/labs/images/".
Fix suggestion: add path "images/" to each image link in .adoc files, e.g. change

image::pipelines-1.png[Simple pipeline with a task and taskrun]

to

image::images/pipelines-1.png[Simple pipeline with a task and taskrun]

I have folked the repository and fixed those in my folk: https://github.com/jackhu008/workshop4

I can raise a PR if required.

[browningjp]

Hi Jack, thanks for raising this issue.

I've had a go deploying the changes, and unfortunately the workshopper application (https://github.com/RedHat-Middleware-Workshops/workshopper) that we use during the workshop expects to find the images in the "images" subdirectory. As a result, the changes you've suggested lead to broken images on the workshopper application. Annoying that GitHub and workshopper have different expectations!

I can think of two possible ways to reconcile this

1. duplicate the images in the repo (in the labs directory, and in the images subdirectory)

2. Add a symbolic link to the repo, so that the images subdirectory points back to the labs directory. Only issue with this is that symbolic links are not always treated the same by different clients (some filesystems don't support them)

What do you think?

[jackhu008]

Hi Jonny,

Thanks for asking. I am afraid that I do not see what inter-dependencies there are between https://github.com/utherp0/workshop4 and (https://github.com/RedHat-Middleware-Workshops/workshopper. Are they not independent? I cannot comment until I understand their inter-dependencies.

https://github.com/utherp0/workshop4 keeps the images for labs documents in an image subfolder "labs/images/". All I have suggested (and implemented in my folk jackhu008) is to change the documents to point images in this subfolder. In this sense, it would follow the same approach as workshoper, i.e. keeping images in a subfolder "images/" of documents.

Jack

[browningjp]

Hi Jack,

The labs in this repo are designed to be consumed by the workshopper application (setup scripts for customer workshops are in setup/playbooks), rather than consumed directly from GitHub.

When referencing an image in asciidoc (e.g. image::pipelines-1.png[Simple pipeline with a task and taskrun]), workshopper looks for the image in the images subdirectory, without needing to include it in the path (e.g. image::images/pipelines-1.png[Simple pipeline with a task and taskrun]). As a result, if you add "/images" to the image path as you have suggested, workshopper will look for the image in images/images/pipelines-1.png, which doesn't exist, so it breaks the images when we use workshopper.

I will have a go at creating a symbolic link to see if we can link images/images back to just /images so that it can work with both GitHub and workshopper.

Jonny

[jackhu008]

Hi Jonny,
Thanks for the explanation. I now understand. The challenge with symbolic links, as you mentioned, is that different clients deal with links differently, e.g. Windows and Linux.

Another option is to review whether it is easy to change the Workshopper application to make it to honour the image path as specified, e.g. image::pipelines-1.png[Simple pipeline with a task and taskrun], instead of injecting "images/" prefix. If this change can be done, then adding "images/" to the .adoc files would work for both.

Jack

[browningjp]

Hi Jack,

I've had a go using the symbolic link approach, but that doesn't seem to work.

I like your suggestion about changing the workshopper application, I'll have a poke around the codebase to see if I can figure it out

Jonny