docs: link tests

[shawnbot]

This runs a link checker (broken-link-checker) against all of our pages and lists all of the broken links. It can do images and metadata in addition to <a> tags, and you can exclude external URLs. The tool requires a running web server, so we run it on the public deployed URL, which is actually way faster than running it against the site in dev mode (locally or on Travis).

I've written a custom "reporter" for the link checker that (IMO) is much easier to read and scan than the blc CLI's. 🤓

Most (all?) of the links marked as broken as of 45cd0ac are to private repos such as github/github (source for unpublished components) and github/design-systems (feedback issues, etc.). I think it's safe to exclude them with --exclude 'https://github.com/github/*', but there's also some value to seeing those links listed out and knowing that there are links listed that will 404 for non-Hubbers.

A nice follow-up to this would be to help PR authors trace the source of the broken links, since most of the files in pages/css are generated by our sync script. The script/check-relative-links script has most of what we'd need to do that: namely, use remark to parse the Markdown and selectAll('link[href="..."]') to find its position in the document. For now, that script exists to identify potential sources of broken links from relative links (../utilities vs. /css/utilities).

This basically ticks off a box in #628 ("All documentation links such as status, npm packages, and view source should work").

[shawnbot]

/cc @emplums on broken-link-checker, which might be useful for primer/components ✨

[shawnbot]

Okay @jonrohan, this is ready for review! ✌️

[shawnbot]

FYI, this is what the output looks like in Travis logs (without color):

Running script/check-links in /home/travis/build/primer/primer/docs...
[go!] https://primer-css-docs-link-test.now.sh/css
[ ✓ ] 109 links on https://primer-css-docs-link-test.now.sh/css
[ ✓ ] 11  unique links on https://primer-css-docs-link-test.now.sh/css/getting-started
[ ✓ ] 16  unique links on https://primer-css-docs-link-test.now.sh/css/principles
[ ✓ ] 8   unique links on https://primer-css-docs-link-test.now.sh/css/tools
[---] skip https://github.com/github/design-systems/issues GitHub private repo
...
[ ✓ ] Excepted 32 links:
[ ✓ ] GitHub private repo https://github.com/github/accessibility
[ ✓ ] GitHub private repo https://github.com/github/design-systems
[ ✓ ] GitHub private repo https://github.com/github/design-systems/issues
...
[ ✓ ] 0 broken links

I made an asciinema recording to show what it looks like locally with:

# cd docs
script/check-links http://localhost:3000/css -v

ProTip: The -m option to script/check-links sets the max open connections per host option, which must be 1 (the default) when you're running the development server or Next will throw errors and fail the link checker. However, if you can speed up the run dramatically by running the production server and cranking that number up to, say, 3 or 5.

[shawnbot]

Interestingly enough, the link checker will not fail the build if the deployed site is unavailable, which seems to be the case as of cf5e649 in #646. I guess that's okay? ¯\_(ツ)_/¯