OpenAPI Specification Rendered with Astro Starlight

[valerii15298]

Repo: https://github.com/valerii15298/openapi-spec
Website: https://valerii15298.github.io/openapi-spec

I just took markdown file for 3.2.0 version and rendered it using Astro Starlight.

Also added fuzzy search with jumps to the headings for quicker navigation:
https://youtu.be/eMxoI0SXpF0

[ralfhandl]

The spec markdown contains ReSpec constructs that are lost in this rendering, for example normative references and the automatically generated section listing them:

What is the purpose of this rendering?

Please don't get me wrong: I'm all for improving the spec rendering and just don't want to lose essential current features.

[valerii15298]

Thanks for checking it out, @ralfhandl !

I do not know how [[YAML|YAML]] should be handled in my case because by default starlight just renders it from markdown file. And that file does not contain references because they are added at build time with ReSpec

Regarding the purpose:
I found myself reading the spec for multiple hours a day, and sometimes I need to quickly jump to different sections, let's say Parameter Object or something else, and respec does not provide such functionality. And since I prefer keyboard navigation, it is a frustration for me.

Also ReSpec has pretty bad ui/ux. On mobile it is even worse. The styling, the font size, the navigation etc... There were many cases when I click on rfc link and it jumps to the bottom where white text is on white background...

And many similar little things. But the main part is navigation with fuzzy search, really. In Astro version I can navigate to different sections quickly(you can check the video I attached).

My subjective opinion as a user, who started relatively recently with the spec and spend 100+ hours reading it: It is ugly, not approachable for beginners and frustrating. And I believe this is true for many users not just me and not just with OpenAPI(whatwg spec also). I had read Parameter Object docs about 40 times, and probably will need to read it as many times again - so I wanna have nice, approachable, easy to navigate UI for myself because I spend a lot of time with it.

And don't get me wrong, I absolutely respect the work you guys did. ReSpec seems to be the standard, whatwg uses it and other orgs, so there are reasons OpenAPI uses it as well. But I wanna read the spec in the format which is more user friendly. And my point is specifically for ReSpec rendering not for the specification itself.

My rendering is mostly for me, I was using it locally for a bit and decided to deploy to GitHub pages and share it if anyone else would find it useful. It lacks some stuff because some info is added via scripts to the ReSpec version. But that is okay for me for now, and maybe I will figure out how to fix that and integrate processing similar how it is done in https://github.com/OAI/OpenAPI-Specification/blob/main/scripts/md2html/md2html.js but it is a bit tricky