Initial Starlight Plugins support

[HiDeoo]

What kind of changes does this PR include?

• Changes or translations of Starlight docs site content
• Changes to Starlight code

Description

• Implements various features of Starlight plugins proposal #753Starlight plugins proposal #962.

This pull request is the beginning of the implementation of a Starlight Plugin API. A lot of details and discussions are available in #753 #962.

The following features are implemented in this first PR:

• config
• updateConfig()
• addIntegration()
• logger

I tried to comment various implementation details, specially around Zod, like why the plugin API is using a totally different schema than the configuration one, why the configuration and configuration updates flowing through the plugin API are not validated (but still properly typed for user convenience) and only the final configuration is validated, etc. but if you have any questions/suggestions, please let me know.

Plugin Example

This PR adds a temporary @astrojs/starlight-search-demo plugin that demonstrates the various features of the plugin API and see how it can be used.

This example is obviously a reference to a potential starlight-algolia kind of plugin that has been requested multiple times on Discord and would also be needed for the Astro docs site. The idea was to see the code required to implement such a plugin and having a custom search bar by only adding the following lines to the astro.config.mjs file:

import starlightSearchDemo from "@astrojs/starlight-search-demo";

starlight({
  plugins: [starlightSearchDemo({ apiKey: "123456" })],
});

Note that this plugin is only meant for demo purposes. It does nothing and even tho we briefly discussed the idea of having official plugins and if we ever decide to make an official Algolia plugin, it feels like this should be done in a separate PR or maybe even a separate repository with all expected features from such a plugin (proper CSS styling, pagefind disabled, tests, etc.).

Note: I think my personal important takeaway from this example is that the injectSettings() API discussed in #753 (and potentially in #861 too for some API changes) could be really useful.

Documentation

This PR adds a "Plugins Reference" page inspired by the Astro Integration API documentation page.
I'm not sure if a guide is needed for the plugin API at this point, as the "use a plugin" section would be pretty much a repeat of the plugins section of the Configuration Reference and may change between plugins and a "create a plugin" section, which I think does not exist for the Astro Integration API, would be pretty much merging the various examples from the "Plugins Reference" page.

I also suggested a change to the showcase to add a new section dedicated for plugins so it can be linked from various places. Obviously, we would need to wait for the first plugin to be published before doing that if we decide to go that way.

Remaining tasks

These tasks should be completed before merging this PR:

• Remove the Starlight Search Demo plugin in its current state
• Remove the Starlight Search Demo plugin from the docs configuration file
• Remove all TODO(HiDeoo) references.
• Add a changeset.

[changeset-bot]

🦋 Changeset detected

Latest commit: 1016921

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@astrojs/starlight	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[delucis]

Super exciting to see this! Will make sure to get you a thorough review ASAP.

[delucis]

Super exciting work @HiDeoo! Left a few initial thoughts and questions.

[HiDeoo]

Thanks a lot for the initial feedback and discussions.

I think all of the points raised are now actionable and I can get back to it and prepare an updated version including all the suggested changes for further review 👍

[HiDeoo]

Add plugins to the user config schema

Turns out this one is a little bit "annoying" due to the recursive types (a user config including plugins which contains a function that pass down a user config that contains plugins…) and our tranforms.

I've setup a small repro in the TS playground of the issue. I've found so far 1 workaround that I describe in the playground but imo this is pretty ugly and I'm not sure if it's even worth it (considering we can do everything suggested without adding plugins to the user config I think).

I'll continue to explore this as I may be missing something obvious or a better way to do this but so far, no luck.

[HiDeoo]

Just pushed a few changes relative to the first review:

• Updated the shape of a plugin to match the one from an Astro integration.
• The configuration passed down to a plugin now also contains the plugins list.
• Refactor the entire validation process:
  1. Before running plugins, the user-provided configuration is validated (we can provided an early feedback to the user)
  2. Then, the user-provided plugins are validated (we can provided an early feedback to the user and indicate that a plugin is not valid)
  3. The plugins are executed
     3.1. If a plugin updates the configuration, we check that it does not try to mutate the plugins list (we have a dedicated error message indicating which plugin is responsible for the error)
     3.2. If a plugin updates the configuration, we validate the new configuration (if the merged configuration is not valid, we have a dedicated error message indicating which plugin is responsible for the error)
  4. We return the final validated configuration and the list of Astro integrations to add
• I added a few comments to help understand the flow of the code regarding the validation process
• A plugin now receives a few new options (astroConfig, command, and isRestart)
• I updated the tests and documentation to reflect the changes
• I slightly updated the demo
  • Fix the color contrast issue ^^
  • I added a button using Preact to show how a plugin should properly test if an Astro integration is already present before adding it

If I did not miss anything, this should covers all the feedback from the first review except the one about adding plugins directly to the user config schema. As commented right above, I still have not a found a proper way to do this that works as expected in all cases but I will keep looking into it.

[HiDeoo]

Updated the PR with the following changes:

• Remove demo plugin and its usage in the docs
• Revert the showcase page to a pre-plugin version
• Remove plugin showcase references from reference/configuration.mdx & reference/plugins.md
• Search and remove all TODO(HiDeoo) references
• Add changeset (not sure what level of detail is expected here)

[delucis]

Really excited we’re getting so close!

I’ve left a last pass of comments on the docs & changeset, but then I think we should be good to go. 🚀

[delucis]

Huh, not sure why CI started failing 🤔

[delucis]

The CI failure is very odd — just ran the build with no issues locally.

[HiDeoo]

The CI failure is very odd — just ran the build with no issues locally.

Same, working fine locally 🤔

[delucis]

From the stack trace it’s almost like it’s complaining about this:

starlight/packages/starlight/index.ts

Line 80 in 00d101b

if (!userConfig.pagefind) return;

But that’s not merged into this PR yet 🤔

[HiDeoo]

Yeah I'm a bit confused as there is no userConfig anymore in the index.ts file anymore

[delucis]

Merged and fixed that to see if it helps!

[delucis]

Looks like that worked? I guess somehow there was some weird code in the CI job?

[delucis]

STAMP OF APPROVAL! ✅

[HiDeoo]

Looks like that worked? I guess somehow there was some weird code in the CI job?

Yeah, I was afraid to try this, see it works and have no clue on why 🤣 I do not have a better explanation ^^

[delucis]

Well, here goes nothing… 🤞