From "monolith" to an Astro preset.

[ringods]

What version of starlight are you using?

0.17.0

What is your idea?

I landed on Astro because of its extensibility: integrations, content collections, frameworks, etc... All of these can be mixed and matched.

Starlight is/feels like a monolith to me, on top of Astro: it assumes that your whole site becomes a documentation site and all the functionality is in a single package/integration. At least, that is how I perceive the current implementation. The sole existence of starlight-blog as a Starlight plugin strengthens me in my opinion.

When chopping Starlight in a number of smaller integrations, we end up with more reusable integrations:

• search functionality: should not only work for the documentation, but for the full site. For instance, see the separate astro-pagefind integration.
• core docs integration:
  • map a content collection to a documentation set having a separate table of contents & inter-page navigation. This maps to Docs Multi-instance Support #956
  • expect a set of component for the rendering, but don't include these. Documents the expectations each component should have/support.
• default UI components: use the current Starlight docs components, but not forced to use these.
• the combination of the separate integrations offered as an Astro preset.

Why is this feature necessary?

A site is never 100% one or the other. With smaller integrations, users will have an easier way of mixing only what they need. The resulting site setup will remain more modular, IMO one of the core premises of Astro.

Do you have examples of this feature in other projects?

No

Participation

• I am willing to submit a pull request for this feature.

[delucis]

Thanks for the feedback @ringmods. I think we can see this from a couple of perspectives. Starlight’s main goal is to provide people with an out-of-the-box docs solution that mostly just works with minimal config or set-up for common use cases, but is also flexible enough to customise. It will however always be less flexible than building in Astro from scratch given it provides opinionated solutions to certain things.

That said, incorporating Starlight alongside other non-Starlight routes is totally do-able. For example, https://terrateam.io/ features completely custom landing and marketing pages and clicking through to the docs section shows Starlight-powered pages. Less dramatically, https://spotlightjs.com/ uses Starlight for all pages, but with customisations to match their branding.

I’d be curious to hear about specific use cases that you got blocked on. For example, you mention search. We could make it easier to re-use Starlight’s default search component to help in this case (we already do expose this, but only in a format designed for our component overrides system, which makes it less easy to use outside of that.