We haven't figured out the auto-updating pages yet,

This would probably be a mix of GitHub Actions:

1. one to publish the new GitHub Pages (or Netlify)
2. one to make sure PRs which update the various yaml files also regenerate the Markdown files or they cant be merged.

initial feedback from the maintainer team

we have a website already at https://securityscorecards.dev/ with some doc info using Netlify, and long term I'd want there to just be one website, instead of having that and a GitHub Pages site. I know we can point our domain (or portions of it) at GitHub pages for example, but is not something that needs to be done from the beginning.

Tagging other @ossf/scorecard-maintainers for thoughts

Thanks for setting this up @ariathaker!

A couple of thoughts/things for the team to consider:

1. GitHub pages supports using custom domains. So we don't need to use the typical github-user.github.io/repository-name url if we don't want to.

2. We would need to tweak the code that generates the checks documentation. I think it would just be a matter of including the necessary header for Jekyll to recognize the page but this change will require dev support.

3. We should remember that changes in the docs have taken place since work on the proof of concept (POC) began. The POC is useful for understanding what the docs could look like/whether we want to invest more time, but if we decide to implement it, we should update it with the docs currently in the main repository not from the POC.

4. GitHub pages either build from the /docs folder or from root. This POC builds from root. We would want the real scorecard docs to build from /docs. There is a current /docs folder. So we may need to adjust our file structure slightly to make sure that things can be built correctly and the doc generation files don't break.

And smaller nits/feedback/opinions:

1. There are two copies of 'Scalable Scorecard"
2. I am not sure I like how the checks documentation is organized (with the table being on the parent page and the breakdown being on the child page). I think these two pages should be on the same level (both children of a shared parent page, both on the top level, or have the pages combined)