How to use <StarlightPage> in actual projects ?

[sgalcheung]

I have some confusion about <StarlightPage>, although some docs were introduced in Using Starlight’s design in custom pages
, but how to handle different source markdown content is not mentioned; this is a point that needs special attention, especially after the release of astro 5.10, which brought a new API: live content collections.

But let’s go back and sort out the possible situations.

• render docs collection comes from a local MD/MDX content
• render a customer collection that comes from a local file, maybe MD/MDX, TXT, or any other content file
• render a customer collection that comes from a remote API
• render a remote fetch API markdown content, not using a collection

For now, if we render using a collection, we must define a content.config.ts file, because Starlight will read this custom docs schema.

starlight/packages/starlight/utils/starlight-page.ts

Line 214 in fc6f311

return userCollections?.docs?.schema ?? docsSchema();

If we direct render some content, don't use a collection, we will not create a content.config.ts file, but this will cause a build error:

[vite]: Rollup failed to resolve import "/Users/sgalcheung/......src/content/config.ts" from "virtual:starlight/collection-config".
This is most likely unintended because it can break your application at runtime.
If you do want to externalize this module explicitly add it to
build.rollupOptions.external
   Stack trace:
     at viteLog (file:///Users/sgalcheung/......node_modules/.pnpm/vite@6.3.2_@types+node@22.5.0_jiti@2.4.2_lightningcss@1.29.2_yaml@2.5.0/node_modules/vite/dist/node/chunks/dep-DG3BLbPj.js:46278:15)
     at onLog (file:///Users/sgalcheung/......node_modules/.pnpm/vite@6.3.2_@types+node@22.5.0_jiti@2.4.2_lightningcss@1.29.2_yaml@2.5.0/node_modules/vite/dist/node/chunks/dep-DG3BLbPj.js:45976:7)
     at Object.logger [as onLog] (file:///Users/sgalcheung/......node_modules/.pnpm/rollup@4.40.0/node_modules/rollup/dist/es/shared/node-entry.js:22583:9)
     at ModuleLoader.resolveDynamicImport (file:///Users/sgalcheung/......node_modules/.pnpm/rollup@4.40.0/node_modules/rollup/dist/es/shared/node-entry.js:21388:58)
  ELIFECYCLE  Command failed with exit code 1.

This error is because of the assumption that the user creates a content.config.ts file and imports it as a virtual module:

starlight/packages/starlight/integrations/virtual-user-config.ts

Line 108 in fc6f311

userCollections = (await import(${JSON.stringify(collectionConfigImportPath)})).collections;

At this point, most people don’t use a collection or customize a docs schema. I think providing a default docs schema is sufficient to initialize <StarlightPage>, but I also have a question: don't we know users only use <StarlightPage>, not use the docs collection?

Next, if we adapt the live content, we have to make a change to render markdown at request time rather build time.
This also gives us a chance to support the renderMarkdown API.

Finally, a <StarlightPage> with request time render markdown will be an awesome feature. 🚀

[HiDeoo]

Thanks for the discussion.

First, I'd like to mention that one important point is that Starlight is built on top Astro, and as we mention, many questions can be answered by checking Astro Docs. Markdown rendering is not different and pretty much everything from the "Markdown in Astro" guide applies to Starlight as well.

At this point, most people don’t use a collection or customize a docs schema. I think providing a default docs schema is sufficient to initialize <StarlightPage>, but I also have a question: don't we know users only use <StarlightPage>, not use the docs collection?

Starlight is designed around content collections, and no matter if you follow the "Getting Started" guide or the manual setup, both either comes with content collections configured or makes you configure them as part of the installation process. Personally, I don't think I've ever seen a Starlight project that doesn't use content collections (this makes sense considering it's part of the current initial setup).

While we can probably change some of our current assumptions around content collections to avoid some potential errors, just like Starlight components, they're designed to be used in a valid Starlight project and do not aim to work outside of it.

Starlight current content collection support is already limited in some ways, e.g. we're limited to a docs content collection, we expect the collection to be located in a specific directory. These limitations are currently in place due to some limitations in Astro, but we definitely hope to improve them in the future.

When it comes to renderMarkdown, once #3239 is fixed, users should be able to use it in Starlight projects as well with the <StarlightPage> component and custom collections. Altho, as mentioned in this discussion, we would also probably need on the long run some API changes in Astro, to properly support all Starlight features using that new API.