Provide more documentation and examples for plugins

[darwinx64]

What is your idea?

I am not very great at programming in javascript and as it is right now Starlight's documentation for plugins is on the lacking side. I propose a more dedicated category for creating plugins specifically as the reference is only a reference and it is only describing a few properties and nothing else. Additionally, an example or template plugin would help. In general, nowhere is it described how to create and develop Starlight plugins, or really are they mentioned anywhere else at all. Information on plugins is just very limited.

I am aware existing plugins do indeed ofcourse exist, however, these plugins are obviously made very integrated to do just one specific thing, and the code for these plugins are not documented. I feel this prevents beginners from learning and making plugins.

Why is this important?

Starlight isn't necessarily feature full, or very customizable, so as Starlight stands currently, I do believe plugins could go a very long way for customizing documentation to a user's needs perfectly and allow them to get exactly what they would like without having to fork Starlight, or do other large measures, just for the sake of customizability.

How does your idea relate to existing docs content?

For clarification, I do think the existing plugins reference page is fine. I am proposing a new category unrelated to the reference, in the documentation, on exclusively the creation of plugins.

Participation

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

[delucis]

Hey @darwinx64! Thanks for the feedback. I agree it would be nice to have a guide for building plugins, not just the reference page we have currently.

plugins could go a very long way for customizing documentation to a user's needs perfectly

Just to clarify this point: plugins can’t do anything a user can’t already do. The main reason for building plugins is to create tools that can be shared and used by multiple users. You can kind of think of them as “presets” in way, that add specific Starlight configuration options.

To give an example, our official Algolia DocSearch plugin includes a custom Search.astro component and sets Starlight’s component override configuration to tell the project to use it. A user could do the same thing manually, but what makes a plugin interesting is that we can then share that specific configuration and make it easier for projects to use it.