Is it possible to use Starlight for only one subpage of the site, instead of it always being at root?
#Use Starlight for one part of the site only
grim tree
zinc widgetBOT
Hi @grim tree. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
Yes, it is possible to use Starlight for only one part of your site, such as a subpath, rather than having it always at the root. The recommended approach is to place all your Starlight documentation content inside a subdirectory of src/content/docs/. For example, if you want your Starlight-powered docs to be available at /guides/, you would organize your content like this:
src/
content/
docs/
guides/
guide.md
index.md
With this setup, all Starlight pages will be served under the /guides/ path of your site. This allows you to keep the rest of your site separate from the Starlight documentation section. Note that, as of now, this approach requires the extra nested directory, but there are plans to improve support for this use case in the future Manual Setup: Tips for existing sites.
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
grim tree
@zinc widget so is it not possible to configure starlight (at astro.config) to deploy at one dedicated subpage only for now, with the other pages being reserved for the rest of the site?
zinc widgetBOT
Let me check the knowledge base for you again. One moment! :books:
Based on the available knowledge sources, there is currently no configuration option in astro.config.mjs to directly set a base path or subpath for Starlight in the way you might with some other integrations. Instead, the recommended method is to organize your documentation content within a subdirectory (e.g., src/content/docs/guides/) so that Starlight pages are generated under that subpath (e.g., /guides/). The rest of your site can use Astro’s standard routing in src/pages/ for other pages.
There is no mention of a dedicated config option to mount Starlight at a specific subpath via configuration alone; the subpath behavior is achieved through directory structure, not a config setting. The documentation also notes that improved support for this use case may be added in the future Manual Setup: Tips for existing sites.
So, to summarize:
You cannot currently configure Starlight in astro.config.mjs to deploy at a dedicated subpage; you must use directory structure to achieve this separation.
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
grim tree
@zinc widget ok so I've decided I want to not use Starlight's docs pages, but I do want to use their components. Is there a way to set Starlight to "pageless" mode so I can use its components (like its Header, Sidebar, etc..)?
zinc widgetBOT
Let me check the knowledge base for you again. One moment! :books:
I'm sorry, but the knowledge sources do not explicitly mention a "pageless" mode or a way to use Starlight solely as a component library without generating documentation pages.
However, the documentation does confirm that you can import and use Starlight’s built-in components (such as Header, Sidebar, etc.) in your own custom pages or components. For example, you can import components like this:
import Header from '@astrojs/starlight/components/Header.astro';
You can use these components in your Astro pages, and the documentation provides examples of reusing built-in components in custom components Reuse a built-in component.
But, there is no information about a configuration option to disable Starlight’s page generation entirely while still making its components available. If you want to avoid generating docs pages, you could simply not add any content to src/content/docs/, but this is not described as an official "pageless" mode in the documentation.
In summary:
- You can use Starlight’s components in your own pages.
- There is no documented "pageless" mode or config to disable docs page generation while keeping components available Using components.