Add recipe for remapping Github URLs to commit

[katrinafyi]

I want to add a docs page for this. The premise is...

---

When you have a link to a file in Github that does not yet exist on main, this can cause problems if link checking is a PR check requirement. This is kind of a circular requirement: the link is broken because it's not merged yet, but the link has to be valid in order to merge.

One fix for this is to remap Github URLs which point to the main branch so that they point to the current commit, instead.

  --remap "https://github\.com/UQ-PAC/BASIL/blob/main https://github.com/UQ-PAC/BASIL/blob/$commit"
  --remap "https://github\.com/UQ-PAC/BASIL/tree/main https://github.com/UQ-PAC/BASIL/tree/$commit"

This way, it checks the links and makes sure that they will exist after merging. This also handles the case where you delete a file in a PR, so it will correctly detect the link as broken.

Other notes:

• Could also use absolute URLs with fixed commit, but can be less preferable. Sometimes, you just want to link to the latest version of the file and flag if the file gets moved.
• For PRs CI actions, $commit should point to the generated merge commit, not the latest commit of the feature branch. This ensures that it also picks up any commits from main which would be present after the PR merge.

[mre]

Yes, sounds helpful. We could add it to the "Github Action Recipes" section. Maybe we could mention it here, too: lycheeverse/lychee-action#238.

And we still have https://github.com/lycheeverse/remaps lying around. We could either mention it there as well or alternatively clean up that repo and merge it with the docs.