Ideally there would be a good mkdocs based checker, but the
one that is out there only validate absolute URLs, which makes
it unsuitable for checking local relative links in the docs.
Adjust the doc build so that we also generate the SUMMARY.md
for mdbook, and use mdbook's link checker to check the links.
Fixup the couple of broken links that it found.
Previously, I was cleaning up some junk like _index directories
generated from the _index.md fragments. I noticed that those
were showing up in the search index, so it is better to exclude
from the outset. mkdocs doesn't natively support the idea of
exclusion, but there is a plugin that does, so use it.
I'd carried over behavior from wezterm where we only considered
tracked markdown files, which could be confusing for newly
authored files: they wouldn't get considered or updated until
they had been committed.
the pages workflow silently corrects these so they go unnoticed,
leaving the corrections to show up for the next person to run
`docs/build.sh`, polluting their later commit with unrelated
changes.
Augment the verify-pages workflow to also run on `main` and
surface the corrections with a failed workflow run.
Wez Furlong