Set up Link Checking for Markdown and Repo Files

[aj-stein-nist]

User Story:

As a NIST OSCAL developer, in order to make sure references to hyperlinked material in the Markdown (and perhaps are other code files in the repository) are still current and good, I want tooling to check the links are valid and feedback provided to developers for current or added hyperlinks.

Goals:

• Check links and minimize issues by Hyperlink needs update #170 through CI/CD.

Dependencies:

{Describe any previous issues or related work that must be completed to start or complete this issue.}

Acceptance Criteria

• All readme documentation affected by the changes in this issue have been updated.
• A Pull Request (PR) is submitted that fully addresses the goals of this User Story. This issue is referenced in the PR.
• The CI-CD build process runs without any reported errors on the PR. This can be confirmed by reviewing that all checks have passed in the PR.

{The items above are general acceptance criteria for all User Stories. Please describe anything else that must be completed for this issue to be considered resolved.}

[aj-stein-nist]

This is up for debate but I thought I would put it here.

[aj-stein-nist]

@david-waltermire-nist and @wendellpiez, thoughts? I will add this to "Needs Discussion" for now.

[aj-stein-nist]

#179 seems to be a consequence of this not existing as well.

[wendellpiez]

We had link checking at some point. It was an impediment because false positives were not uncommon - it was too draconian. Then didn't the link checkers have trouble with some links or domains? Also, link checking at commit time under CI/CD is not ideal.

Could this be addressed by better support for link checking in Markdown editors, over/above CI/CD?

Also, an easy way to say "don't check this link" as an emergency escape hatch? This would presumably be a tagging convention respected by the link checker and supported by Hugo.

One approach to this would be to run link checking over the published repository at intervals and report, but not bind this to commits (or do so only as warning not blocker), i.e. run it independently. Then participants would have ready access to a list of known or suspected broken links, to be kept as short as possible.

[wendellpiez]

One other thing - a link checker is an excellent way to avoid a certain kind of bone-headed error in generated documentation.