Substitute relative paths with absolute links.

Use Jekyll link tag to specify paths instead of relative markdown paths, like so:

'[Home](../../index.md)' -> '[Home]({% link docs/index.md %})'.
'[Gitlab Logo](../../../img/gitlab-logo.png)' -> '[Gitlab Logo]({% link img/gitlab-logo.png %}).

This is a follow up to issue #65 (closed) and has a few additional benefits. Currently, a large number (most?) of the relative links to other pages on the site are broken. This should hopefully fix that problem. Also, if you write your links in this style, Jekyll will fail to build if the link doesn't point to an actual file. This would allow us to more easily change the directory structure, knowing that if we invalidate any links, it will be very obvious in testing.

The disadvantages are that markdown files will no longer have image preview in the Gitlab UI, and links to specific parts of pages (e.g., ../index.md#heading2) aren't possible in this style (at the moment, most of the links are completely broken anyway).

Sorry for the enormous PR! I thought it would be best to do it all in one go. I tried to get all of the links, but most likely I missed one or two.

WARNING: this will only work if the Jekyll version is above 4.0, see this section of the Jekyll docs for more information.

Fantastic, thanks Séamus!

merged

mentioned in commit f2a844fa

post-merge note:

• Something broke between opening of the merge request and the actual merge. The pipeline initially passed but failed when merging. The log file indicated an error that the "csv" library is missing, which is strange (?).
• After poking around, I've added the csv gem (and the base64 gem due to a similar error afterwards) to the Gemfile which seems to have fixed the error.
• However, our current jekyll setup is getting out of date (see also the avalanche of deprecation warnings in the latest log file.
• Séamus @fhv480, if you have time at some point to look into this with me, that would be awesome. (The current setup is a patchwork of different people adding/changing things over several years, i.e. very messy, so sorting this out might be a bit painful.)

Hi Bernd

Yes, I noticed that as well. The problem seems to have first occurred when you updated the copyright year, which shouldn't have broken anything in itself. From what I can tell, csv and base64 were formerly part of the Ruby standard lib, but were moved to separate libraries in the recent 3.4 release and now have to be explicitly declared (see https://rubyreferences.github.io/rubychanges/3.4.html#default-gems-that-became-bundled). Should we specify a particular Ruby Docker image version in gitlab-ci.yml, (and also maybe commit Gemfile.lock to Git) in order to avoid issues like this in future?

I am definitely happy to look into updating the setup with you, although I am not that familiar with Ruby/Jekyll or SASS (which seems to be where most deprecation warnings come from) so I will need to get up to speed a bit.

mentioned in issue #66 (closed)