mirror of
https://github.com/aljazceru/contextvm-docs.git
synced 2025-12-19 15:04:24 +01:00
134 lines
4.6 KiB
Markdown
134 lines
4.6 KiB
Markdown
---
|
||
title: Manual Setup
|
||
description: Learn how to configure Starlight manually to add it to an existing Astro project.
|
||
---
|
||
|
||
import { Tabs, TabItem } from '@astrojs/starlight/components';
|
||
|
||
The quickest way to create a new Starlight site is using `create astro` as shown in the [Getting Started guide](/getting-started/#create-a-new-project).
|
||
If you want to add Starlight to an existing Astro project, this guide will explain how.
|
||
|
||
## Set up Starlight
|
||
|
||
To follow this guide, you’ll need an existing Astro project.
|
||
|
||
### Add the Starlight integration
|
||
|
||
Starlight is an [Astro integration](https://docs.astro.build/en/guides/integrations-guide/). Add it to your site by running the `astro add` command in your project’s root directory:
|
||
|
||
<Tabs syncKey="pkg">
|
||
<TabItem label="npm">
|
||
```sh
|
||
npx astro add starlight
|
||
```
|
||
|
||
</TabItem>
|
||
<TabItem label="pnpm">
|
||
```sh
|
||
pnpm astro add starlight
|
||
```
|
||
</TabItem>
|
||
<TabItem label="Yarn">
|
||
```sh
|
||
yarn astro add starlight
|
||
```
|
||
</TabItem>
|
||
|
||
</Tabs>
|
||
|
||
This will install the required dependencies and add Starlight to the `integrations` array in your Astro config file.
|
||
|
||
### Configure the integration
|
||
|
||
The Starlight integration is configured in your `astro.config.mjs` file.
|
||
|
||
Add a `title` to get started:
|
||
|
||
```js ins={8}
|
||
// astro.config.mjs
|
||
import { defineConfig } from 'astro/config';
|
||
import starlight from '@astrojs/starlight';
|
||
|
||
export default defineConfig({
|
||
integrations: [
|
||
starlight({
|
||
title: 'My delightful docs site',
|
||
}),
|
||
],
|
||
});
|
||
```
|
||
|
||
Find all available options in the [Starlight configuration reference](/reference/configuration/).
|
||
|
||
### Configure content collections
|
||
|
||
Starlight is built on top of Astro’s [content collections](https://docs.astro.build/en/guides/content-collections/), which are configured in the `src/content.config.ts` file.
|
||
|
||
Create or update the content config file, adding a `docs` collection that uses Starlight’s [`docsLoader`](/reference/configuration/#docsloader) and [`docsSchema`](/reference/configuration/#docsschema):
|
||
|
||
```js ins={3-4,7}
|
||
// src/content.config.ts
|
||
import { defineCollection } from 'astro:content';
|
||
import { docsLoader } from '@astrojs/starlight/loaders';
|
||
import { docsSchema } from '@astrojs/starlight/schema';
|
||
|
||
export const collections = {
|
||
docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
|
||
};
|
||
```
|
||
|
||
Starlight also supports the [`legacy.collections` flag](https://docs.astro.build/en/reference/legacy-flags/) where collections are handled using the legacy content collections implementation.
|
||
This is useful if you have an existing Astro project and are unable to make any changes to collections at this time to use a loader.
|
||
|
||
### Add content
|
||
|
||
Starlight is now configured and it’s time to add some content!
|
||
|
||
Create a `src/content/docs/` directory and start by adding an `index` file.
|
||
This will be the homepage of your new site:
|
||
|
||
```md
|
||
---
|
||
# src/content/docs/index
|
||
title: My docs
|
||
description: Learn more about my project in this docs site built with Starlight.
|
||
---
|
||
|
||
Welcome to my project!
|
||
```
|
||
|
||
Starlight uses file-based routing, which means every Markdown, MDX, or Markdoc file in `src/content/docs/` will turn into a page on your site. Frontmatter metadata (the `title` and `description` fields in the example above) can change how each page is displayed.
|
||
See all the available options in the [frontmatter reference](/reference/frontmatter/).
|
||
|
||
## Tips for existing sites
|
||
|
||
If you have an existing Astro project, you can use Starlight to quickly add a documentation section to your site.
|
||
|
||
### Use Starlight at a subpath
|
||
|
||
To add all Starlight pages at a subpath, place all your docs content inside a subdirectory of `src/content/docs/`.
|
||
|
||
For example, if Starlight pages should all start with `/guides/`, add your content in the `src/content/docs/guides/` directory:
|
||
|
||
import { FileTree } from '@astrojs/starlight/components';
|
||
|
||
<FileTree>
|
||
|
||
- src/
|
||
- content/
|
||
- docs/
|
||
- **guides/**
|
||
- guide
|
||
- index
|
||
- pages/
|
||
- astro.config.mjs
|
||
|
||
</FileTree>
|
||
|
||
In the future, we plan to support this use case better to avoid the need for the extra nested directory in `src/content/docs/`.
|
||
|
||
### Use Starlight with SSR
|
||
|
||
To enable SSR, follow the [“On-demand Rendering Adapters”](https://docs.astro.build/en/guides/on-demand-rendering/) guide in Astro’s docs to add a server adapter to your Starlight project.
|
||
|
||
Documentation pages generated by Starlight are pre-rendered by default regardless of your project's output mode. To opt out of pre-rendering your Starlight pages, set the [`prerender` config option](/reference/configuration/#prerender) to `false`. |