search

HiDeoo / starlight-openapi

Starlight plugin to generate documentation from OpenAPI/Swagger specifications
https://starlight-openapi.vercel.app
MIT License
112 stars 14 forks source link

Co-location with vanilla Starlight #2

Closed azan-n closed 1 year ago

azan-n commented 1 year ago

Is your feature request related to a problem?

I've been planning docs revamps for more than two years now and the project is still at a standstill. I can see that Starlight has matured adequately and I thank @HiDeoo for the efforts they have put into this project.

I had been trying my own way of building static OpenAPI docs equivalent to those built by Redoc. You can read more about it here: https://azan-n.pages.dev/projects/2023-08-18t000000000z/

While I was keen on having to use redoc's internal parsers instead of SwaggerParser like this project, I think it is best for this project to disconnect from redoc and it's internal implementations.

Describe the solution you'd like

I'm convinced that I can help out with this since I am well-versed with swagger, docs, and Astro. Currently, Starlight has a hacky way of having a home page (from what I can tell) and no way to have a top-level navigation that could possibly have the following sections 'Guides, Web API Reference, SDK Reference, Changelog'.

I recognize that this could be a large change, but allowing multiple instances of the sidebar, and essentially Starlight to exist on multiple paths could allow this to be a versatile docs tool.

Describe alternatives you've considered

Slate, Mintlify, Readme.io (too expensive but does the job), Nextra (would need custom OpenAPI support and frankly isn't quite SSG as I like things to be), Docusaurus (not even close to SSG).

Additional Context

No response

HiDeoo commented 1 year ago

Thanks for your feedback and also sharing your blog post, really interesting.

Currently, Starlight has a hacky way of having a home page (from what I can tell)

The home page in Starlight is a basic md or mdx file named index.mdx in the src/content/docs/ directory so it behaves pretty much like any other pages.

no way to have a top-level navigation that could possibly have the following sections 'Guides, Web API Reference, SDK Reference, Changelog'

There is currently an opened issue that I think match exactly the use case you are describing. Like you said, there's a lot of considerations for a feature that have such a large impact on the entire documentation. We are trying to gather use cases, see every parts that would have to interact with such a change and discuss how the API should look like.

I think it would be great to share your feedback in this issue, it would be really helpful for us to have more infos and make sure to consider every use cases.

Considering the main point is mostly Starlight related, I'll close this issue if that is ok and we can continue the discussion in the issue I linked above 🙌

azan-n commented 1 year ago

The home page in Starlight is a basic md or mdx file named index.mdx in the src/content/docs/ directory so it behaves pretty much like any other pages.

This has been an issue with Nextra as well. They are now pivoting to an index.tsx (https://github.com/shuding/nextra/pull/2070) mainly because it gets limiting if you want the homepage to be a pretty-looking landing page of sorts.

I think it would be great to share your feedback in this issue, it would be really helpful for us to have more infos and make sure to consider every use cases.

Thanks. I'll be sure to join in on the discussion.