Re: Migration of git-scm.com to a static web site: ready for review/testing

From: Johannes Schindelin <johannes.schindelin@gmx.de>
Date: Sep 11, 2024, 22:18 UTC
Message-ID: <db0aeda7-f266-8b1a-517f-c0bea4d4e02b@gmx.de>
In-Reply-To: <ZWVIRXodL9pQZbtj@pobox.com>

Hi Todd,

On Mon, 27 Nov 2023, Todd Zullinger wrote:

Show 35 quoted lines

> Johannes Schindelin wrote:
> > I found https://lychee.cli.rs/#/ in the meantime and figured out how to
> > use it in a local setup:
>
> Nice.  That's much faster.
>
> > My most recent lychee run results in 0 broken links.
> >
> > As a bonus, some of the links that are currently broken on
> > https://git-scm.com/ are fixed in https://git.github.io/git-scm.com/.
> > For example, following the `Pull Request Referləri` link at the top of
> > https://git-scm.com/book/az/v2/Appendix-C:-Git-%C6%8Fmrl%C9%99ri-Plumbing-%C6%8Fmrl%C9%99ri/
> > leads to a 404. But following it in
> > https://git.github.io/git-scm.com/book/az/v2/Appendix-C:-Git-%C6%8Fmrl%C9%99ri-Plumbing-%C6%8Fmrl%C9%99ri/
> > directs the browser to the correct URL:
> > https://git.github.io/git-scm.com/book/az/v2/GitHub-Bir-Layih%C9%99nin-Saxlan%C4%B1lmas%C4%B1/#_pr_refs
> >
> > Another thing that is broken on https://git-scm.com/ are the footnotes in
> > the Czech translation of the ProGit book. These were broken in the Hugo
> > version, too, but now they are fixed. See e.g.
> > https://dscho.github.io/git-scm.com/book/cs/v2/Z%C3%A1klady-pr%C3%A1ce-se-syst%C3%A9mem-Git-Zobrazen%C3%AD-historie-reviz%C3%AD/#_footnotedef_7
> > and note that the Rails App redirects to
> > https://git-scm.com/book/cs/v2/Z%C3%A1klady-pr%C3%A1ce-se-syst%C3%A9mem-Git-Zobrazen%C3%AD-historie-reviz%C3%AD/ch00/_footnotedef_7
> > when clicking on the `[7]`, which 404s.
> >
> > Could you double-check that the links in the current version?
>
> Since I had it already, I ran linkchecker again.  It found
> 25 errors.  I'll attach the output, though I'm not sure if
> the list will pass it along or not.
>
> It looks like a number of errors are due to '?' characters
> in the generated links, e.g.:
>
> https://git.github.io/git-scm.com/book/en/v2/Getting-Started-What-is-Git?/

_That_ was quite a quest to investigate and to fix. The problem here is, of course, the difference in how question marks are handled in file:// vs https:// URLs: in the latter, they separate the path part from the query. Therefore, they need to be URI-encoded in https:// URLs.

I verified manually (and with a Playwright-based test that is now run as part of every deployment and of every PR build) that these URLs with question marks in them work.

As to using `lychee` to verify the links, I went down quite a rabbit hole to allow using it on the very same files that are being deployed, with relative URLs and "ugly" ones at that, too (i.e. with the `.html` suffix that you do not need to specify when accessing `.html` files on GitHub Pages). This has not yet been released in an official version, therefore I need to use the `nightly` version for the time being.

The good news is that the link checking is integrated into the deployment and PR builds in https://github.com/git/git-scm.com/pull/1804. That will allow us to catch broken links faster. One caveat, though: for robustness (and also for speed), only internal links are checked. Links pointing to other websites are not validated, but it is easy to do that manually by running Lychee without the `--offline` flag.

Ciao, Johannes