Should we-organize our GitHub pages to a separate repo (by way of a directory on main)?

[handrews]

Splitting this out from #3766, to which it is still somewhat related as we should consider the impact on how many PRs to how many different branches are required for a change that spans the spec and the registries.

Originally, gh-pages sites needed to be on a gh-pages branch that (as ours does) typically has a completely different layout than main. That is no longer required, and it is much more common to deploy from a directory on main. Or at least from a directory on a branch that is no more different from main than any other working branch.

[Bellangelo]

I totally agree with this one. This might be a personal preference but I usually find it confusing when each branch is a different project completely. I can start with this one after this is closed #1823

[handrews]

Note that the current build process seems spread across both main and gh-pages, plus duplication for the OAS and Arazzo specs, which probably needs to be unraveled.

Also, there are infrastructure bits under the curren top-level directory on main which should probably be pushed down into the directory that will replace the gh-pages branch to reduce clutter.

[frankkilcommins]

We should consider having a dedicated repo for spec.openapis.org? As we have now moved to a multi-specification project (and likely more coming - Overlays), nesting the website housing the specs under one of the specification repos is a little confusing.

Each separate specification repo that wants to publish can issue PRs to the repo housing the HTML versions and other information relevant to spec.openapis.org. We could then have the same process in place for both OpenAPI-Specification and Arazzo-Specification repos.

[Bellangelo]

@frankkilcommins Should each spec has its own domain maybe? For example, arazzo.openapis.org, overlays.openapis.org etc. Or a single repo for everyone is the best option?

[handrews]

@Bellangelo We want a unified brand across the different specs, so I think we'll want to stick with spec.openapis.org.