lychee: avoid problems between --base-url and relative paths

When a HTML file in a subdirectory references a file in the same
subdirectory via a relative path (e.g. Pagefind Playground's
`<link rel="stylesheet" href="./pagefind-playground.css" />` in
`pagefind/playground/index.html`), lychee's `--base-url` option causes
unwanted transformations: It pretends that that file is actually at the
base URL. For example, running with `--base-url
https://dscho.github.io/git-scm.com` will pretend that that CSS is at
https://dscho.github.io/git-scm.com/pagefind-playground.css, skipping
the `pagefind/playground/` altogether.

This is a known issue, and lychee introduced a `--root-dir` option to
accommodate. However, there remain problems, see e.g.
lycheeverse/lychee#1718.

In our concrete case, we cannot easily use `--root-dir` because when we
deploy to forks, the absolute paths have a `/git-scm.com/` prefix yet
that is not the suffix of the absolute path of the `public/` folder!

Even though it is not easily used, it _is_ possible: by constructing a
separate path and adding a symbolic link whose name _is_ `git-scm.com`
and which points to the `public/` directory. Then the parent directory
of that symlink can be used as `--root-dir`.

There is still one caveat: lychee ignores symbolic links when populating
the initial set of files from a given base directory. So let's pass the
path to that symlink, with trailing slash, as the base directory
parameter. That seems to work.

This change is needed because we are about to enable Pagefind's shiny
new Playground, which has an `index.html` file in
`/pagefind/playground/` that references a `.css` in the same directory
via a relative link (which would be mishandled when using `--base-url`).

Signed-off-by: Johannes Schindelin <[email protected]>

Author: dscho

.github/actions/deploy-to-github-pages/action.yml

@@ -126,10 +126,33 @@ runs:
           -H "Content-Type: application/json" \
           -d '{ "purge_everything": true }'
 
-    - name: construct `--remap` options for lychee
+    - name: construct `--remap` options, root-dir for lychee
       id: remap
       shell: bash
       run: |
+        # Prepare the root-dir for use with the `--root-dir` option
+        echo "root-dir-arg=$PWD/root-dir" >>$GITHUB_OUTPUT &&
+        case "$base_url" in
+        https://*/?*|http://*/?*)
+          # The base URL is not at the top-level of the URL
+          subdir="${base_url#http*://*/}"
+          target="root-dir/${subdir%/}"
+          source="$(echo "${subdir%/}" | sed 's/[^/]*/../g')/public"
+          mkdir -p "${target%/*}" &&
+          ln -s "$source" "$target" &&
+          echo "root-dir=$target/" >>$GITHUB_OUTPUT
+          ;;
+        https://*|http://*)
+          # The base URL is at the top-level of the URL
+          ln -s public root-dir &&
+          echo 'root-dir=root-dir/' >>$GITHUB_OUTPUT
+          ;;
+        *)
+          echo "::error::Unexpected base_url '$base_url'" >&2
+          echo exit 1
+          ;;
+        esac || exit
+
         echo "result=$(echo "$base_url" |
           sed 's|^\(.*\)\(/git-scm\.com\)$|^(\1)?\2(.*)|') file://$PWD/public\$2" \
           >>$GITHUB_OUTPUT
@@ -163,7 +186,7 @@ runs:
         args: >-
           --offline
           --fallback-extensions html
-          --base '${{ env.base_url }}'
+          --root-dir '${{ steps.remap.outputs.root-dir-arg }}'
           --remap '${{ steps.remap.outputs.result }}'
           ${{ steps.remap.outputs.remap-dotdot }}
           ${{ steps.remap.outputs.remap-git-scm }}
@@ -174,7 +197,7 @@ runs:
           --exclude file:///Pfad/zum/Repo.git/
           --exclude file:///chemin/du/d%C3%A9p%C3%B4t.git/
           --exclude file:///srv/git/project.git
-          public/
+          '${{ steps.remap.outputs.root-dir }}'
         output: lychee.md
         jobSummary: true
         fail: false