gh-pages: Generalize registry site to publications #4226
Conversation
The spec site main page had gotten a bit muddled. This organizes it into three distinct sections (Specifications, Registries, and Non-normative JSON Schemas) and adds an intro paragraph that links to each section as well as the Learn and Tools site. The reason for moving the schemas is that I almost couldn't find the Overlay specification (I added Overlay to the shortcut links at the top as well as it was missing). The registries are in-between as they are less-well-known, and I added shortcuts to the individual registries as it made the sections feel more similar. I renamed the overall site "Publications" instead of "Registry", as it does a lot more now. It could be "Specifications" if we would rather stick with the "spec site" terminology.
handrews
added
script
handrews
changed the title
| @@ -63,6 +63,8 @@ aux_links: | |||
| - "https://spec.openapis.org/oas/latest.html" | |||
| "Latest Arazzo Specification": | |||
| - "https://spec.openapis.org/arazzo/latest.html" | |||
| "Latest Overlay Specification": | |||
| - "https://spec.openapis.org/overlay/latest.html" | |||
There was a problem hiding this comment.
This pushes the search field narrower and cuts off "Search OpenAPI Initia"
There was a problem hiding this comment.
Yeah, Jekyll and Liquid are horrible and have very few layout options. Maybe change "Specification" to "Spec" and change "Search OpenAPI Initiative Registry" to just "Search". because it does search the whole spec site AFAICT.
There was a problem hiding this comment.
@notEthan I truncated "specification" to "spec". It turns out Jekyll/Liquid put whatever the site's title is in the Search box and I have no idea how to turn it off or change it, and I'm way past my Jekyll/Liquid frustration level at this point as they are the absolute worst I've been forced to work with and fill me with rage every time I attempt any improvement. So someone else can deal with that.
There was a problem hiding this comment.
What I need to do let me know please thank you
Explain the not-entirely-intuitive schema naming for OAS 3.1, and link to issues discussing various schema FAQs.
|
I've now further updated this with more guidance around schema naming, use, and FAQs. The preview has also been updated. |
The spec site main page had gotten a bit muddled. This organizes it into three distinct sections (Specifications, Registries, and Non-normative JSON Schemas) and adds an intro paragraph that links to each section as well as the Learn and Tools site.
The reason for moving the schemas is that I almost couldn't find the Overlay specification (I added Overlay to the shortcut links at the top as well as it was missing).
The registries are in-between as they are less-well-known, and I added shortcuts to the individual registries as it made the sections feel more similar.
I renamed the overall site "Publications" instead of "Registry", as it does a lot more now. It could be "Specifications" if we would rather stick with the "spec site" terminology.
Partial preview: https://handrews.github.io/renderings/oas/spec/ (Note that while the page-local and registry page links work, because they are relative, the spec and schema links do not because they use absolute paths and I can't figure out how to fix that without editing the generated html- you can insert
/renderings/oas/specbetween the domain and the beginning of the path for pages that 404 to see what they should be; the spec shortcut buttons at the top use absolute URLs and go to the production spec site)