CI: broken link check at PR time

[jasonmadigan]

Add a broken link check step at PR time, rather than merge/publish (too late).

We do nightly builds right now which do do mkdocs strict builds which spot most broken links. We also have that separate broken link checker action that can be manually dispatched, that can check for broken external links too (handy).

[david-martin]

@jasonmadigan is this not already the case for PRs?
For example, https://github.com/Kuadrant/docs.kuadrant.io/actions/runs/12793070413/job/35665005128 , which ran for this PR #174

The build job runs mkdocs build -s, which exits with a non zero code and an an error like this if there is a broken link within the site.

WARNING -  Doc file 'index.md' contains a link 'thing.md', but the target is not found among documentation files.
...
...
Traceback (most recent call last):
  File "/opt/app-root/lib64/python3.9/site-packages/mkdocs/commands/build.py", line 351, in build
    raise Abort(f'Aborted with {msg} in strict mode!')
mkdocs.exceptions.Abort: Aborted with 1 warnings in strict mode!

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/opt/app-root/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/opt/app-root/lib64/python3.9/site-packages/click/core.py", line 1157, in __call__
    return self.main(*args, **kwargs)
  File "/opt/app-root/lib64/python3.9/site-packages/click/core.py", line 1078, in main
    rv = self.invoke(ctx)
  File "/opt/app-root/lib64/python3.9/site-packages/click/core.py", line 1688, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/opt/app-root/lib64/python3.9/site-packages/click/core.py", line 1434, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/opt/app-root/lib64/python3.9/site-packages/click/core.py", line 783, in invoke
    return __callback(*args, **kwargs)
  File "/opt/app-root/lib64/python3.9/site-packages/mkdocs/__main__.py", line 288, in build_command
    build.build(cfg, dirty=not clean)
  File "/opt/app-root/lib64/python3.9/site-packages/mkdocs/commands/build.py", line 357, in build
    config.plugins.on_build_error(error=e)
  File "/opt/app-root/lib64/python3.9/site-packages/mkdocs/plugins.py", line 605, in on_build_error
    return self.run_event('build_error', error=error)
  File "/opt/app-root/lib64/python3.9/site-packages/mkdocs/plugins.py", line 568, in run_event
    result = method(**kwargs)
  File "/opt/app-root/lib64/python3.9/site-packages/mkdocs_multirepo_plugin/plugin.py", line 361, in on_build_error
    shutil.rmtree(str(self.temp_dir))
  File "/usr/lib64/python3.9/shutil.py", line 724, in rmtree
    onerror(os.lstat, path, sys.exc_info())
  File "/usr/lib64/python3.9/shutil.py", line 722, in rmtree
    orig_st = os.lstat(path)
FileNotFoundError: [Errno 2] No such file or directory: '/docs/temp_dir'

[jasonmadigan]

I'd somehow missed that this still worked, I think because we have two builds for dev vs release. I don't think this is necessary now.