Convert docs to mkdocs, material, mermaid

[ahouseholder]

Creating this as a draft PR to start to address the following:

• fixes Move away from PDF as the main SSVC documentation vehicle #295
• fixes Use Diátaxis Framework to restructure SSVC documentation #294

Periodically copying this branch to https://certcc.github.io/SSVC-staging for review

[ahouseholder]

I'm toggling this PR out of draft mode. Not because it contains a finished implementation of webified SSVC documentation, but because it contains a sufficient implementation that we can clean up as we go.

The difficulty in making such a large change (from a set of .md files that were intended to compile into a monolithic .pdf to a set of .md files intended to be a web site) is that it's highly disruptive to other tasks either in flight or enqueued, so the longer-lived this branch is, the more it inhibits forward progress.

However, that also means that we need to commit to this way forward, because merging this PR will represent a discontinuity with the past. Notably, as it stands, this branch breaks the ability to build a PDF from the assembled documentation.

That is not to say that we couldn't reconstitute such a thing in the future. For example, a giant markdown file with

{% include-markdown "file1.md" %}
{% include-markdown "file2.md" %}
...
{% include-markdown "fileN.md" %}

could be rendered into a PDF (hint: https://pypi.org/project/mkdocs-pandoc-plugin/ is a candidate).

As I see it, there are two major options to be had at the moment:

Merge now, fix later

Commit to this approach, break some things now and clean them up as we go

1. merge this branch sooner than later
2. continue with content development tasks, cleaning up broken links etc. as we go
3. fix things like PDF generation afterwards

Fix now, merge later

Fix all the anticipated breaks first, then commit to this approach

1. figure out things like PDF generation first
2. fix broken links and get the content 100% into web-ready form
3. only merge this branch once those things are done
4. continue with content development tasks

---

My strong preference is toward merge now, fix later, because it allows the most things to move forward in parallel.

On the other hand, the fix now, merge later approach puts us in a position of "we shouldn't do X yet because Y will mess that up, so we should wait until after Y is done to do X". And doing that could delay further content development indefinitely until we get through this bottleneck.

I'm adding more than the usual number of reviewers to this because I'd like us to have a reasonable consensus to this before we finalize the decision though.

You can preview the staged website at https://certcc.github.io/SSVC-staging

[ahouseholder]

I should note that if there is concern about breaking https://certcc.github.io/SSVC as it currently exists (with just the ssvc-calc code), I totally get that.

Option 1

One option could be that we could:

• clone the main branch into a develop branch
• retarget this PR against the develop branch

And we could agree by consensus to continue work against develop until we think we're ready to replace main with it. This would be a change to how we've done it in the past by doing PRs against main, but it doesn't seem like an insurmountable challenge.

[ahouseholder]

Option 2

Alternatively, we could

• clone main to a production branch, and reset the Github Pages publishing process to watch production
• merge this PR into main and continue on our merry way

Both the main / develop and production / main options are functionally identical, just that PRs against main will be a bit easier to deal with in the second than in the first.

---

In either case, we still need to occasionally copy either the develop or the main branch (as appropriate to the chosen option) over to the staging branch of the CERTCC/SSVC-staging repository to update the preview.

I'm leaning toward Option 2, interested in discussion about that too.

[cgyarbrough]

I believe we discussed this in the meeting on 9/5/23 and I agree with Allen that we should proceed with the conversion to dynamic content first. While it may be useful to have a pdf version of some sort (probably for executive review), I think that we should move to the web-based documentation and do fixes and cleanup as we go. Of course if this would go against any SEI/CMU publication standards or requirements then we should discuss that prior to heading down the online doc path.

[ahouseholder]

#304 implements Option 2 from this comment, so we can now merge this PR into main without affecting the published calculator (because it's now drawing from the publish branch instead of main.)

[laurie-tyz]

As agreed in the meeting.

[ahouseholder]

@j--- any concerns about merging this into main?

[j---]

No concerns. Sorry for the delay.

…

-- best, Jono From my mobile, please excuse brevity

[ahouseholder]

Ok, changes merged into main. Also synced this over to CERTCC/SSVC-staging which means it's published at https://certcc.github.io/SSVC-staging too.