External Link Checking

The external link check tests if links between pages of The Turing Way and other websites work. This is a useful tool which helps us ensure that when users click a link they are brought to a working page.

There is a GitHub workflow which regularly tests external links in the book and posts a list of broken links to an issue. This section explains the process which updates the broken links issue.

Workflow

The workflow is dispatched according to a schedule. The schedule uses the POSIX cron format to specify when the workflow should run. The workflow is currently configured to run once per week at midnight on Monday in the UTC+00:00 time zone.

Lychee is used to check the book’s external links after building the book. If the book fails to build then the workflow will also fail. The workflow uses cached results from previous runs to avoid the need to recheck all links every time the check is run. However, this does mean that the results may not be up to date.

The GitHub runner’s GitHub token is specified as an environment variable for the Lychee action. This prevents false negatives due to rate limiting when testing links to GitHub.

The Lychee configuration in the root of the repository controls the behaviour of Lychee. The configuration is a TOML file. An example configuration file with explanations can be found in the Lychee documentation.

The configuration file can be used to improve the usefulness of the broken links issue. In particular, it is possible to exclude domains which are known to produce false negatives using the --exclude argument on the command line or the equivalent exclude key in the configuration file.

Lychee produces a report of broken links and saves this to a Markdown file. The workflow then concatenates this report with an issue header and updates the broken links issue.

Issue

The broken links issue is #3171. The information in the issue header aims to explain the output and provide some guidance for fixing broken links. That information is not duplicated here. Improvements to the explanation or guidance should be made to the issue header as any changes made to the issue will be overwritten when it is next updated.

Running the Checks Locally

You can run the external link checking process locally using Lychee after building the book. From the repository root,

$ lychee --config ./lychee.toml book/website/_build/html/**/*.html