Lyche link-checking

[nikitawootten-nist]

This PR sets up link checking with Hugo (#5)

Progress

• Lychee link checking wired into Makefile
• Update pages workflow to optionally perform link checking (allow the result to be ignored on workflow_dispatch)
• Fix makefile rebuilding Hugo on dependent targets
• Fix Lychee behavior on relative links Fix the model documentation pipeline's relative link handling: Awaiting Remove trailing slash in -page options for modeldoc pipeline fixing relative path traversals metaschema-xslt#75
• Fix all links
• Update pages workflow to:
  • run periodic checks
  • produce PR comments
  • upload results as an artifact
• Document usage

Side-effects

• Parametrized the pages GHA workflow for use with workflow_dispatch events
• Added aliases for pages that are no longer needed, and bad links from old OSCAL Metaschemas
• Fixed about 900 dead links

[nikitawootten-nist]

Note: the workflow will fail due to new permissions being added to the action. Refer to the test PR for results: nikitawootten-nist#1

[wendellpiez]

Looks awesome, nice work on a pesky problem.

Interesting to think about: whether OSCAL repo wants its own XSpec, whether calling, or sometimes switching in for the XSpec lower down.

[nikitawootten-nist]

@iMichaela @aj-stein-nist should the release-notes be removed/aliased to GitHub's release page as part of this PR?

[Compton-US]

Verified that the ssp and cdef links are working.

[aj-stein-nist]

@iMichaela @aj-stein-nist should the release-notes be removed/aliased to GitHub's release page as part of this PR?

I am fine with removing the redundant data or we need to update a checklist and start adding a page with PR review to lag a release. @iMichaela suggested as much: I think if we want to do that, we want to update the ("new") news page after the release is drafted. That means I am happy moving the currently (and frequently) out of sync release page (since we can edit GitHub notes quickly, the website) less so.

We can wait to see if Michaela agrees.

[aj-stein-nist]

I had to understand the CI/CD error but it appears to relate to the permissions because the PR opened from a fork, not a branch of the upstream, @nikitawootten-nist. I am still happy with it and it stays approved.

[nikitawootten-nist]

I had to understand the CI/CD error but it appears to relate to the permissions because the PR opened from a fork, not a branch of the upstream, @nikitawootten-nist. I am still happy with it and it stays approved.

Unfortunately GitHub's UX for PRs from a fork isn't great. Any new permissions are denied without explanation. I have a twin PR on my fork demonstrating that the commits do build and produce linkcheck comments: nikitawootten-nist#1

[aj-stein-nist]

We can wait to see if Michaela agrees.

@iMichaela agreed to this approach. @nikitawootten-nist will work on removing releases page, AJ will update procedures for release docs to update it and include an update to the news page.

[nikitawootten-nist]

Final checks passed: https://github.com/nikitawootten-nist/OSCAL-Reference/actions/runs/6329066790/job/17188603346

Merging now

[aj-stein-nist]

Guidance updated in core wiki in the commit below.

https://github.com/usnistgov/OSCAL/wiki/OSCAL-Release-Checklist/45da2cb9fd540ef9e1a8ed195940e4f5326913f6

News page approach backported per usnistgov/OSCAL-Pages#52.