mirror of
https://github.com/aljazceru/contextvm-docs.git
synced 2025-12-18 22:44:25 +01:00
fix: broken links
This commit is contained in:
gzuuus
@@ -4,7 +4,7 @@ import starlight from '@astrojs/starlight';
|
||||
|
||||
// https://astro.build/config
|
||||
export default defineConfig({
|
||||
site: 'https://contextvm.github.io/',
|
||||
site: 'https://contextvm.github.io',
|
||||
base: 'contextvm-docs',
|
||||
integrations: [
|
||||
starlight({
|
||||
|
||||
@@ -1,474 +0,0 @@
|
||||
---
|
||||
title: Customizing Starlight
|
||||
description: Learn how to make your Starlight site your own with your logo, custom fonts, landing page design and more.
|
||||
---
|
||||
|
||||
import { Tabs, TabItem, FileTree, Steps } from '@astrojs/starlight/components';
|
||||
|
||||
Starlight provides sensible default styling and features, so you can get started quickly with no configuration needed.
|
||||
When you want to start customizing the look and feel of your Starlight site, this guide has you covered.
|
||||
|
||||
## Add your logo
|
||||
|
||||
Adding a custom logo to the site header is a quick way to add your individual branding to a Starlight site.
|
||||
|
||||
<Steps>
|
||||
|
||||
1. Add your logo image file to the `src/assets/` directory:
|
||||
|
||||
<FileTree>
|
||||
|
||||
- src/
|
||||
- assets/
|
||||
- **my-logo.svg**
|
||||
- content/
|
||||
- astro.config.mjs
|
||||
|
||||
</FileTree>
|
||||
|
||||
2. Add the path to your logo as Starlight’s [`logo.src`](/reference/configuration/#logo) option in `astro.config.mjs`:
|
||||
|
||||
```diff lang="js"
|
||||
// astro.config.mjs
|
||||
import { defineConfig } from 'astro/config';
|
||||
import starlight from '@astrojs/starlight';
|
||||
|
||||
export default defineConfig({
|
||||
integrations: [
|
||||
starlight({
|
||||
title: 'Docs With My Logo',
|
||||
logo: {
|
||||
+ src: './src/assets/my-logo.svg',
|
||||
},
|
||||
}),
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
</Steps>
|
||||
|
||||
By default, the logo will be displayed alongside your site’s `title`.
|
||||
If your logo image already includes the site title, you can visually hide the title text by setting the `replacesTitle` option.
|
||||
The `title` text will still be included for screen readers so that the header remains accessible.
|
||||
|
||||
```js {5}
|
||||
starlight({
|
||||
title: 'Docs With My Logo',
|
||||
logo: {
|
||||
src: './src/assets/my-logo.svg',
|
||||
replacesTitle: true,
|
||||
},
|
||||
}),
|
||||
```
|
||||
|
||||
### Light and dark logo variants
|
||||
|
||||
You can display different versions of your logo in light and dark modes.
|
||||
|
||||
<Steps>
|
||||
|
||||
1. Add an image file for each variant to `src/assets/`:
|
||||
|
||||
<FileTree>
|
||||
|
||||
- src/
|
||||
- assets/
|
||||
- **light-logo.svg**
|
||||
- **dark-logo.svg**
|
||||
- content/
|
||||
- astro.config.mjs
|
||||
|
||||
</FileTree>
|
||||
|
||||
2. Add the path to your logo variants as the `light` and `dark` options instead of `src` in `astro.config.mjs`:
|
||||
|
||||
```diff lang="js"
|
||||
starlight({
|
||||
title: 'Docs With My Logo',
|
||||
logo: {
|
||||
+ light: './src/assets/light-logo.svg',
|
||||
+ dark: './src/assets/dark-logo.svg',
|
||||
},
|
||||
}),
|
||||
```
|
||||
|
||||
</Steps>
|
||||
|
||||
## Enable sitemap
|
||||
|
||||
Starlight has built-in support for generating a sitemap. Enable sitemap generation by setting your URL as `site` in `astro.config.mjs`:
|
||||
|
||||
```js {4}
|
||||
// astro.config.mjs
|
||||
|
||||
export default defineConfig({
|
||||
site: 'https://stargazers.club',
|
||||
integrations: [starlight({ title: 'Site with sitemap' })],
|
||||
});
|
||||
```
|
||||
|
||||
Learn how to [add a sitemap link to `robots.txt`](https://docs.astro.build/en/guides/integrations-guide/sitemap/#sitemap-link-in-robotstxt) in the Astro Docs.
|
||||
|
||||
## Page layout
|
||||
|
||||
By default, Starlight pages use a layout with a global navigation sidebar and a table of contents that shows the current page headings.
|
||||
|
||||
You can apply a wider page layout without sidebars by setting [`template: splash`](/reference/frontmatter/#template) in a page’s frontmatter.
|
||||
This works particularly well for landing pages and you can see it in action on the [homepage of this site](/).
|
||||
|
||||
```md {5}
|
||||
---
|
||||
# src/content/docs/index
|
||||
|
||||
title: My Landing Page
|
||||
template: splash
|
||||
---
|
||||
```
|
||||
|
||||
## Table of contents
|
||||
|
||||
Starlight displays a table of contents on each page to make it easier for readers to jump to the heading they are looking for.
|
||||
You can customize — or even disable — the table of contents globally in the Starlight integration or on a page-by-page basis in frontmatter.
|
||||
|
||||
By default, `<h2>` and `<h3>` headings are included in the table of contents. Change which headings levels to include site-wide using the `minHeadingLevel` and `maxHeadingLevel` options in your [global `tableOfContents`](/reference/configuration/#tableofcontents). Override these defaults on an individual page by adding the corresponding [frontmatter `tableOfContents`](/reference/frontmatter/#tableofcontents) properties:
|
||||
|
||||
<Tabs syncKey="config-type">
|
||||
<TabItem label="Frontmatter">
|
||||
|
||||
```md {4-6}
|
||||
---
|
||||
# src/content/docs/example
|
||||
title: Page with only H2s in the table of contents
|
||||
tableOfContents:
|
||||
minHeadingLevel: 2
|
||||
maxHeadingLevel: 2
|
||||
---
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Global config">
|
||||
|
||||
```js {7}
|
||||
// astro.config.mjs
|
||||
|
||||
defineConfig({
|
||||
integrations: [
|
||||
starlight({
|
||||
title: 'Docs with custom table of contents config',
|
||||
tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 2 },
|
||||
}),
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
Disable the table of contents entirely by setting the `tableOfContents` option to `false`:
|
||||
|
||||
<Tabs syncKey="config-type">
|
||||
<TabItem label="Frontmatter">
|
||||
|
||||
```md {4}
|
||||
---
|
||||
# src/content/docs/example
|
||||
title: Page without a table of contents
|
||||
tableOfContents: false
|
||||
---
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Global config">
|
||||
|
||||
```js {7}
|
||||
// astro.config.mjs
|
||||
|
||||
defineConfig({
|
||||
integrations: [
|
||||
starlight({
|
||||
title: 'Docs with table of contents disabled globally',
|
||||
tableOfContents: false,
|
||||
}),
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Social links
|
||||
|
||||
Starlight has built-in support for adding links to your social media accounts to the site header via the [`social`](/reference/configuration/#social) option in the Starlight integration.
|
||||
|
||||
Each entry in the `social` array must be an object with three properties:
|
||||
|
||||
- `icon`: one of Starlight’s [built-in icons](/reference/icons/), e.g. `"github"`.
|
||||
- `label`: an accessible label for the link, e.g. `"GitHub"`.
|
||||
- `href`: the URL for the link, e.g. `"https://github.com/withastro/starlight"`.
|
||||
|
||||
The following example adds links to the Astro Discord chat and the Starlight GitHub repository:
|
||||
|
||||
```js {9-16}
|
||||
// astro.config.mjs
|
||||
import { defineConfig } from 'astro/config';
|
||||
import starlight from '@astrojs/starlight';
|
||||
|
||||
export default defineConfig({
|
||||
integrations: [
|
||||
starlight({
|
||||
title: 'Docs With Social Links',
|
||||
social: [
|
||||
{ icon: 'discord', label: 'Discord', href: 'https://astro.build/chat' },
|
||||
{
|
||||
icon: 'github',
|
||||
label: 'GitHub',
|
||||
href: 'https://github.com/withastro/starlight',
|
||||
},
|
||||
],
|
||||
}),
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
## Edit links
|
||||
|
||||
Starlight can display an “Edit page” link in each page’s footer.
|
||||
This makes it easy for a reader to find the file to edit to improve your docs.
|
||||
For open-source projects in particular, this can help encourage contributions from your community.
|
||||
|
||||
To enable edit links, set [`editLink.baseUrl`](/reference/configuration/#editlink) to the URL used to edit your repository in the Starlight integration config.
|
||||
The value of `editLink.baseUrl` will be prepended to the path to the current page to form the full edit link.
|
||||
|
||||
Common patterns include:
|
||||
|
||||
- GitHub: `https://github.com/USER_NAME/REPO_NAME/edit/BRANCH_NAME/`
|
||||
- GitLab: `https://gitlab.com/USER_NAME/REPO_NAME/-/edit/BRANCH_NAME/`
|
||||
|
||||
If your Starlight project is not in the root of your repository, include the path to the project at the end of the base URL.
|
||||
|
||||
This example shows the edit link configured for the Starlight docs, which live in the `docs/` subdirectory on the `main` branch of the `withastro/starlight` repository on GitHub:
|
||||
|
||||
```js {9-11}
|
||||
// astro.config.mjs
|
||||
import { defineConfig } from 'astro/config';
|
||||
import starlight from '@astrojs/starlight';
|
||||
|
||||
export default defineConfig({
|
||||
integrations: [
|
||||
starlight({
|
||||
title: 'Docs With Edit Links',
|
||||
editLink: {
|
||||
baseUrl: 'https://github.com/withastro/starlight/edit/main/docs/',
|
||||
},
|
||||
}),
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
## Custom 404 page
|
||||
|
||||
Starlight sites display a simple 404 page by default.
|
||||
You can customize this by adding a `404` (or `404.mdx`) file to your `src/content/docs/` directory:
|
||||
|
||||
<FileTree>
|
||||
|
||||
- src/
|
||||
- content/
|
||||
- docs/
|
||||
- **404**
|
||||
- index
|
||||
- astro.config.mjs
|
||||
|
||||
</FileTree>
|
||||
|
||||
You can use all of Starlight’s page layout and customization techniques in your 404 page. For example, the default 404 page uses the [`splash` template](#page-layout) and [`hero`](/reference/frontmatter/#hero) component in frontmatter:
|
||||
|
||||
```md {4,6-8}
|
||||
---
|
||||
# src/content/docs/404
|
||||
title: '404'
|
||||
template: splash
|
||||
editUrl: false
|
||||
hero:
|
||||
title: '404'
|
||||
tagline: Page not found. Check the URL or try using the search bar.
|
||||
---
|
||||
```
|
||||
|
||||
### Disabling the default 404 page
|
||||
|
||||
If your project requires an entirely customized 404 layout, you can create a `src/pages/404.astro` route and set the [`disable404Route`](/reference/configuration/#disable404route) config option to disable Starlight’s default route:
|
||||
|
||||
```js {9}
|
||||
// astro.config.mjs
|
||||
import { defineConfig } from 'astro/config';
|
||||
import starlight from '@astrojs/starlight';
|
||||
|
||||
export default defineConfig({
|
||||
integrations: [
|
||||
starlight({
|
||||
title: 'Docs With Custom 404',
|
||||
disable404Route: true,
|
||||
}),
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
## Custom fonts
|
||||
|
||||
By default, Starlight uses sans-serif fonts available on a user’s local device for all text.
|
||||
This ensures documentation loads quickly in a font that is familiar to each user, without requiring extra bandwidth to download large font files.
|
||||
|
||||
If you must add a custom font to your Starlight site, you can set up fonts to use in custom CSS files or with any other [Astro styling technique](https://docs.astro.build/en/guides/styling/).
|
||||
|
||||
### Set up fonts
|
||||
|
||||
If you already have font files, follow the [local set-up guide](#set-up-local-font-files).
|
||||
To use Google Fonts, follow the [Fontsource set-up guide](#set-up-a-fontsource-font).
|
||||
|
||||
#### Set up local font files
|
||||
|
||||
<Steps>
|
||||
|
||||
1. Add your font files to a `src/fonts/` directory and create an empty `font-face.css` file:
|
||||
|
||||
<FileTree>
|
||||
|
||||
- src/
|
||||
- content/
|
||||
- fonts/
|
||||
- **CustomFont.woff2**
|
||||
- **font-face.css**
|
||||
- astro.config.mjs
|
||||
|
||||
</FileTree>
|
||||
|
||||
2. Add an [`@font-face` declaration](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face) for each of your fonts in `src/fonts/font-face.css`.
|
||||
Use a relative path to the font file in the `url()` function.
|
||||
|
||||
```css
|
||||
/* src/fonts/font-face.css */
|
||||
|
||||
@font-face {
|
||||
font-family: 'Custom Font';
|
||||
/* Use a relative path to the local font file in `url()`. */
|
||||
src: url('./CustomFont.woff2') format('woff2');
|
||||
font-weight: normal;
|
||||
font-style: normal;
|
||||
font-display: swap;
|
||||
}
|
||||
```
|
||||
|
||||
3. Add the path to your `font-face.css` file to Starlight’s `customCss` array in `astro.config.mjs`:
|
||||
|
||||
```diff lang="js"
|
||||
// astro.config.mjs
|
||||
import { defineConfig } from 'astro/config';
|
||||
import starlight from '@astrojs/starlight';
|
||||
|
||||
export default defineConfig({
|
||||
integrations: [
|
||||
starlight({
|
||||
title: 'Docs With a Custom Typeface',
|
||||
customCss: [
|
||||
+ // Relative path to your @font-face CSS file.
|
||||
+ './src/fonts/font-face.css',
|
||||
],
|
||||
}),
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
</Steps>
|
||||
|
||||
#### Set up a Fontsource font
|
||||
|
||||
The [Fontsource](https://fontsource.org/) project simplifies using Google Fonts and other open-source fonts.
|
||||
It provides npm modules you can install for the fonts you want to use and includes ready-made CSS files to add to your project.
|
||||
|
||||
<Steps>
|
||||
|
||||
1. Find the font you want to use in [Fontsource’s catalog](https://fontsource.org/).
|
||||
This example will use [IBM Plex Serif](https://fontsource.org/fonts/ibm-plex-serif).
|
||||
|
||||
2. Install the package for your chosen font.
|
||||
You can find the package name by clicking “Install” on the Fontsource font page.
|
||||
|
||||
<Tabs syncKey="pkg">
|
||||
|
||||
<TabItem label="npm">
|
||||
|
||||
```sh
|
||||
npm install @fontsource/ibm-plex-serif
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem label="pnpm">
|
||||
|
||||
```sh
|
||||
pnpm add @fontsource/ibm-plex-serif
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem label="Yarn">
|
||||
|
||||
```sh
|
||||
yarn add @fontsource/ibm-plex-serif
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
</Tabs>
|
||||
|
||||
3. Add Fontsource CSS files to Starlight’s `customCss` array in `astro.config.mjs`:
|
||||
|
||||
```diff lang="js"
|
||||
// astro.config.mjs
|
||||
import { defineConfig } from 'astro/config';
|
||||
import starlight from '@astrojs/starlight';
|
||||
|
||||
export default defineConfig({
|
||||
integrations: [
|
||||
starlight({
|
||||
title: 'Docs With a Custom Typeface',
|
||||
customCss: [
|
||||
+ // Fontsource files for to regular and semi-bold font weights.
|
||||
+ '@fontsource/ibm-plex-serif/400.css',
|
||||
+ '@fontsource/ibm-plex-serif/600.css',
|
||||
],
|
||||
}),
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
Fontsource ships multiple CSS files for each font. See the [Fontsource documentation](https://fontsource.org/docs/getting-started/install#4-weights-and-styles) on including different weights and styles to understand which to use.
|
||||
|
||||
</Steps>
|
||||
|
||||
### Use fonts
|
||||
|
||||
To apply the font you set up to your site, use your chosen font’s name in a [custom CSS file](/guides/css-and-tailwind/#custom-css-styles).
|
||||
For example, to override Starlight’s default font everywhere, set the `--sl-font` custom property:
|
||||
|
||||
```css
|
||||
/* src/styles/custom.css */
|
||||
|
||||
:root {
|
||||
--sl-font: 'IBM Plex Serif', serif;
|
||||
}
|
||||
```
|
||||
|
||||
You can also write more targeted CSS if you want to apply your font more selectively.
|
||||
For example, to only set a font on the main content, but not the sidebars:
|
||||
|
||||
```css
|
||||
/* src/styles/custom.css */
|
||||
|
||||
main {
|
||||
font-family: 'IBM Plex Serif', serif;
|
||||
}
|
||||
```
|
||||
|
||||
Follow the [custom CSS instructions](/guides/css-and-tailwind/#custom-css-styles) to add your styles to your site.
|
||||
@@ -1,140 +0,0 @@
|
||||
---
|
||||
title: Getting Started
|
||||
description: Learn how to start building your next documentation site with Starlight by Astro.
|
||||
---
|
||||
|
||||
import { Tabs, TabItem } from '@astrojs/starlight/components';
|
||||
|
||||
Starlight is a full-featured documentation theme built on top of the [Astro](https://astro.build) framework.
|
||||
This guide will help you get started with a new project.
|
||||
See the [manual setup instructions](/manual-setup/) to add Starlight to an existing Astro project.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Create a new project
|
||||
|
||||
Create a new Astro + Starlight project by running the following command in your terminal:
|
||||
|
||||
<Tabs syncKey="pkg">
|
||||
<TabItem label="npm">
|
||||
|
||||
```sh
|
||||
npm create astro@latest -- --template starlight
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="pnpm">
|
||||
|
||||
```sh
|
||||
pnpm create astro --template starlight
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Yarn">
|
||||
|
||||
```sh
|
||||
yarn create astro --template starlight
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This will create a new [project directory](/guides/project-structure/) with all the necessary files and configurations for your site.
|
||||
|
||||
:::tip[See it in action]
|
||||
Try Starlight in your browser:
|
||||
[open the template on StackBlitz](https://stackblitz.com/github/withastro/starlight/tree/main/examples/basics).
|
||||
:::
|
||||
|
||||
### Start the development server
|
||||
|
||||
When working locally, [Astro’s development server](https://docs.astro.build/en/reference/cli-reference/#astro-dev) lets you preview your work and automatically refreshes your browser when you make changes.
|
||||
|
||||
Inside your project directory, run the following command to start the development server:
|
||||
|
||||
<Tabs syncKey="pkg">
|
||||
<TabItem label="npm">
|
||||
|
||||
```sh
|
||||
npm run dev
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="pnpm">
|
||||
|
||||
```sh
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Yarn">
|
||||
|
||||
```sh
|
||||
yarn dev
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
This will log a message to your terminal with the URL of your local preview.
|
||||
Open this URL to start browsing your site.
|
||||
|
||||
### Add content
|
||||
|
||||
Starlight is ready for you to add new content, or bring your existing files!
|
||||
|
||||
Add new pages to your site by creating Markdown files in the `src/content/docs/` directory.
|
||||
|
||||
Read more about file-based routing and support for MDX and Markdoc files in the [“Pages”](/guides/pages/) guide.
|
||||
|
||||
### Next steps
|
||||
|
||||
- **Configure:** Learn about common options in [“Customizing Starlight”](/guides/customization/).
|
||||
- **Navigate:** Set up your sidebar with the [“Sidebar Navigation”](/guides/sidebar/) guide.
|
||||
- **Components:** Discover built-in cards, tabs, and more in the [“Components”](/components/using-components/) guide.
|
||||
- **Deploy:** Publish your work with the [“Deploy your site”](https://docs.astro.build/en/guides/deploy/) guide in the Astro docs.
|
||||
|
||||
## Updating Starlight
|
||||
|
||||
:::tip
|
||||
Because Starlight is beta software, there will be frequent updates and improvements.
|
||||
Be sure to update Starlight regularly!
|
||||
:::
|
||||
|
||||
Starlight is an Astro integration. You can update it and other Astro packages by running the following command in your terminal:
|
||||
|
||||
<Tabs syncKey="pkg">
|
||||
<TabItem label="npm">
|
||||
|
||||
```sh
|
||||
npx @astrojs/upgrade
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="pnpm">
|
||||
|
||||
```sh
|
||||
pnpm dlx @astrojs/upgrade
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
<TabItem label="Yarn">
|
||||
|
||||
```sh
|
||||
yarn dlx @astrojs/upgrade
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
See the [Starlight changelog](https://github.com/withastro/starlight/blob/main/packages/starlight/CHANGELOG) for a full list of the changes made in each release.
|
||||
|
||||
## Troubleshooting Starlight
|
||||
|
||||
Use the [project configuration](/reference/configuration/) and [individual page frontmatter configuration](/reference/frontmatter/) reference pages to ensure that your Starlight site is configured and functioning properly.
|
||||
See the guides in the sidebar for help adding content and customizing your Starlight site.
|
||||
|
||||
If your answer cannot be found in these docs, please visit the [full Astro Docs](https://docs.astro.build) for complete Astro documentation.
|
||||
Your question may be answered by understanding how Astro works in general, underneath this Starlight theme.
|
||||
|
||||
You can also check for any known [Starlight issues on GitHub](https://github.com/withastro/starlight/issues), and get help in the [Astro Discord](https://astro.build/chat/) from our active, friendly community! Post questions in our `#support` forum with the "starlight" tag, or visit our dedicated `#starlight` channel to discuss current development and more!
|
||||
@@ -1,134 +0,0 @@
|
||||
---
|
||||
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`.
|
||||
@@ -1,47 +0,0 @@
|
||||
---
|
||||
title: Project Structure
|
||||
description: Learn how to organize files in your Starlight project.
|
||||
---
|
||||
|
||||
This guide will show you how a Starlight project is organized and what the different files in your project do.
|
||||
|
||||
Starlight projects generally follow the same file and directory structure as other Astro projects. See [Astro’s project structure documentation](https://docs.astro.build/en/basics/project-structure/) for more detail.
|
||||
|
||||
## Files and directories
|
||||
|
||||
- `astro.config.mjs` — The Astro configuration file; includes the Starlight integration and configuration.
|
||||
- `src/content.config.ts` — Content collections configuration file; adds Starlight’s frontmatter schemas to your project.
|
||||
- `src/content/docs/` — Content files. Starlight turns each ``, `.mdx` or `.mdoc` file in this directory into a page on your site.
|
||||
- `src/content/i18n/` (optional) — Translation data to support [internationalization](/guides/i18n/).
|
||||
- `src/` — Other source code and files (components, styles, images, etc.) for your project.
|
||||
- `public/` — Static assets (fonts, favicon, PDFs, etc.) that will not be processed by Astro.
|
||||
|
||||
## Example project contents
|
||||
|
||||
A Starlight project directory might look like this:
|
||||
|
||||
import { FileTree } from '@astrojs/starlight/components';
|
||||
|
||||
<FileTree>
|
||||
|
||||
- public/
|
||||
- favicon.svg
|
||||
- src/
|
||||
- assets/
|
||||
- logo.svg
|
||||
- screenshot.jpg
|
||||
- components/
|
||||
- CustomButton.astro
|
||||
- InteractiveWidget.jsx
|
||||
- content/
|
||||
- docs/
|
||||
- guides/
|
||||
- 01-getting-started
|
||||
- 02-advanced
|
||||
- index.mdx
|
||||
- content.config.ts
|
||||
- astro.config.mjs
|
||||
- package.json
|
||||
- tsconfig.json
|
||||
|
||||
</FileTree>
|
||||
@@ -1,234 +0,0 @@
|
||||
---
|
||||
title: Site Search
|
||||
description: Learn about Starlight’s built-in site search features and how to customize them.
|
||||
tableOfContents:
|
||||
maxHeadingLevel: 4
|
||||
---
|
||||
|
||||
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
|
||||
|
||||
By default, Starlight sites include full-text search powered by [Pagefind](https://pagefind.app/), which is a fast and low-bandwidth search tool for static sites.
|
||||
|
||||
No configuration is required to enable search. Build and deploy your site, then use the search bar in the site header to find content.
|
||||
|
||||
## Hide content in search results
|
||||
|
||||
### Exclude a page
|
||||
|
||||
To exclude a page from your search index, add [`pagefind: false`](/reference/frontmatter/#pagefind) to the page’s frontmatter:
|
||||
|
||||
```md title="src/content/docs/not-indexed" ins={3}
|
||||
---
|
||||
title: Content to hide from search
|
||||
pagefind: false
|
||||
---
|
||||
```
|
||||
|
||||
### Exclude part of a page
|
||||
|
||||
Pagefind will ignore content inside an element with the [`data-pagefind-ignore`](https://pagefind.app/docs/indexing/#removing-individual-elements-from-the-index) attribute.
|
||||
|
||||
In the following example, the first paragraph will display in search results, but the contents of the `<div>` will not:
|
||||
|
||||
```md title="src/content/docs/partially-indexed" ins="data-pagefind-ignore"
|
||||
---
|
||||
title: Partially indexed page
|
||||
---
|
||||
|
||||
This text will be discoverable via search.
|
||||
|
||||
<div data-pagefind-ignore>
|
||||
|
||||
This text will be hidden from search.
|
||||
|
||||
</div>
|
||||
```
|
||||
|
||||
## Alternative search providers
|
||||
|
||||
### Algolia DocSearch
|
||||
|
||||
If you have access to [Algolia’s DocSearch program](https://docsearch.algolia.com/) and want to use it instead of Pagefind, you can use the official Starlight DocSearch plugin.
|
||||
|
||||
<Steps>
|
||||
|
||||
1. Install `@astrojs/starlight-docsearch`:
|
||||
|
||||
<Tabs syncKey="pkg">
|
||||
|
||||
<TabItem label="npm">
|
||||
|
||||
```sh
|
||||
npm install @astrojs/starlight-docsearch
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem label="pnpm">
|
||||
|
||||
```sh
|
||||
pnpm add @astrojs/starlight-docsearch
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem label="Yarn">
|
||||
|
||||
```sh
|
||||
yarn add @astrojs/starlight-docsearch
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
</Tabs>
|
||||
|
||||
2. Add DocSearch to your Starlight [`plugins`](/reference/configuration/#plugins) config in `astro.config.mjs` and pass it your Algolia `appId`, `apiKey`, and `indexName`:
|
||||
|
||||
```js ins={4,10-16}
|
||||
// astro.config.mjs
|
||||
import { defineConfig } from 'astro/config';
|
||||
import starlight from '@astrojs/starlight';
|
||||
import starlightDocSearch from '@astrojs/starlight-docsearch';
|
||||
|
||||
export default defineConfig({
|
||||
integrations: [
|
||||
starlight({
|
||||
title: 'Site with DocSearch',
|
||||
plugins: [
|
||||
starlightDocSearch({
|
||||
appId: 'YOUR_APP_ID',
|
||||
apiKey: 'YOUR_SEARCH_API_KEY',
|
||||
indexName: 'YOUR_INDEX_NAME',
|
||||
}),
|
||||
],
|
||||
}),
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
</Steps>
|
||||
|
||||
With this updated configuration, the search bar on your site will now open an Algolia modal instead of the default search modal.
|
||||
|
||||
#### DocSearch configuration
|
||||
|
||||
The Starlight DocSearch plugin supports customizing the DocSearch component with the following inline options:
|
||||
|
||||
- `maxResultsPerGroup`: Limit the number of results displayed for each search group. Default is `5`.
|
||||
- `disableUserPersonalization`: Prevent DocSearch from saving a user’s recent searches and favorites to local storage. Default is `false`.
|
||||
- `insights`: Enable the Algolia Insights plugin and send search events to your DocSearch index. Default is `false`.
|
||||
- `searchParameters`: An object customizing the [Algolia Search Parameters](https://www.algolia.com/doc/api-reference/search-api-parameters/).
|
||||
|
||||
##### Additional DocSearch options
|
||||
|
||||
A separate configuration file is required to pass function options like `transformItems()` or `resultsFooterComponent()` to the DocSearch component.
|
||||
|
||||
<Steps>
|
||||
|
||||
1. Create a TypeScript file exporting your DocSearch configuration.
|
||||
|
||||
```ts
|
||||
// src/config/docsearch.ts
|
||||
import type { DocSearchClientOptions } from '@astrojs/starlight-docsearch';
|
||||
|
||||
export default {
|
||||
appId: 'YOUR_APP_ID',
|
||||
apiKey: 'YOUR_SEARCH_API_KEY',
|
||||
indexName: 'YOUR_INDEX_NAME',
|
||||
getMissingResultsUrl({ query }) {
|
||||
return `https://github.com/algolia/docsearch/issues/new?title=${query}`;
|
||||
},
|
||||
// ...
|
||||
} satisfies DocSearchClientOptions;
|
||||
```
|
||||
|
||||
2. Pass the path to your configuration file to the Starlight DocSearch plugin in `astro.config.mjs`.
|
||||
|
||||
```js {11-13}
|
||||
// astro.config.mjs
|
||||
import { defineConfig } from 'astro/config';
|
||||
import starlight from '@astrojs/starlight';
|
||||
import starlightDocSearch from '@astrojs/starlight-docsearch';
|
||||
|
||||
export default defineConfig({
|
||||
integrations: [
|
||||
starlight({
|
||||
title: 'Site with DocSearch',
|
||||
plugins: [
|
||||
starlightDocSearch({
|
||||
clientOptionsModule: './src/config/docsearch.ts',
|
||||
}),
|
||||
],
|
||||
}),
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
</Steps>
|
||||
|
||||
See the [DocSearch JavaScript client API Reference](https://docsearch.algolia.com/docs/api/) for all supported options.
|
||||
|
||||
#### Translating the DocSearch UI
|
||||
|
||||
DocSearch only provides English UI strings by default.
|
||||
Add translations of the modal UI for your language using Starlight’s built-in [internationalization system](/guides/i18n/#translate-starlights-ui).
|
||||
|
||||
<Steps>
|
||||
|
||||
1. Extend Starlight’s `i18n` content collection definition with the DocSearch schema in `src/content.config.ts`:
|
||||
|
||||
```js ins={5} ins=/{ extend: .+ }/
|
||||
// src/content.config.ts
|
||||
import { defineCollection } from 'astro:content';
|
||||
import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders';
|
||||
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
|
||||
import { docSearchI18nSchema } from '@astrojs/starlight-docsearch/schema';
|
||||
|
||||
export const collections = {
|
||||
docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
|
||||
i18n: defineCollection({
|
||||
loader: i18nLoader(),
|
||||
schema: i18nSchema({ extend: docSearchI18nSchema() }),
|
||||
}),
|
||||
};
|
||||
```
|
||||
|
||||
2. Add translations to your JSON files in `src/content/i18n/`.
|
||||
|
||||
These are the English defaults used by DocSearch:
|
||||
|
||||
```json title="src/content/i18n/en.json"
|
||||
{
|
||||
"docsearch.searchBox.resetButtonTitle": "Clear the query",
|
||||
"docsearch.searchBox.resetButtonAriaLabel": "Clear the query",
|
||||
"docsearch.searchBox.cancelButtonText": "Cancel",
|
||||
"docsearch.searchBox.cancelButtonAriaLabel": "Cancel",
|
||||
"docsearch.searchBox.searchInputLabel": "Search",
|
||||
|
||||
"docsearch.startScreen.recentSearchesTitle": "Recent",
|
||||
"docsearch.startScreen.noRecentSearchesText": "No recent searches",
|
||||
"docsearch.startScreen.saveRecentSearchButtonTitle": "Save this search",
|
||||
"docsearch.startScreen.removeRecentSearchButtonTitle": "Remove this search from history",
|
||||
"docsearch.startScreen.favoriteSearchesTitle": "Favorite",
|
||||
"docsearch.startScreen.removeFavoriteSearchButtonTitle": "Remove this search from favorites",
|
||||
|
||||
"docsearch.errorScreen.titleText": "Unable to fetch results",
|
||||
"docsearch.errorScreen.helpText": "You might want to check your network connection.",
|
||||
|
||||
"docsearch.footer.selectText": "to select",
|
||||
"docsearch.footer.selectKeyAriaLabel": "Enter key",
|
||||
"docsearch.footer.navigateText": "to navigate",
|
||||
"docsearch.footer.navigateUpKeyAriaLabel": "Arrow up",
|
||||
"docsearch.footer.navigateDownKeyAriaLabel": "Arrow down",
|
||||
"docsearch.footer.closeText": "to close",
|
||||
"docsearch.footer.closeKeyAriaLabel": "Escape key",
|
||||
"docsearch.footer.searchByText": "Search by",
|
||||
|
||||
"docsearch.noResultsScreen.noResultsText": "No results for",
|
||||
"docsearch.noResultsScreen.suggestedQueryText": "Try searching for",
|
||||
"docsearch.noResultsScreen.reportMissingResultsText": "Believe this query should return results?",
|
||||
"docsearch.noResultsScreen.reportMissingResultsLinkText": "Let us know."
|
||||
}
|
||||
```
|
||||
|
||||
</Steps>
|
||||
@@ -42,4 +42,4 @@ This documentation is structured to guide you from initial setup to advanced imp
|
||||
- **Proxy & Gateway**: Explains how to use the bridging components.
|
||||
- **Tutorials**: Provides practical, step-by-step examples.
|
||||
|
||||
Let's begin by setting up your environment in the [Quick Overview](./getting-started/quick-overview/).
|
||||
Let's begin by setting up your environment in the [Quick Overview](../getting-started/quick-overview/).
|
||||
@@ -8,7 +8,7 @@ hero:
|
||||
file: ../../assets/contextvm-logo.svg
|
||||
actions:
|
||||
- text: Get Started
|
||||
link: /getting-started/quick-overview/
|
||||
link: ../getting-started/quick-overview/
|
||||
icon: right-arrow
|
||||
- text: View on GitHub
|
||||
link: https://github.com/contextvm/ts-sdk
|
||||
|
||||
@@ -5,7 +5,7 @@ description: An abstract class that provides the core functionality for all Nost
|
||||
|
||||
# Base Nostr Transport
|
||||
|
||||
The `BaseNostrTransport` is an abstract class that provides the core functionality for all Nostr-based transports in the `@contextvm/sdk`. It serves as the foundation for the [`NostrClientTransport`](./nostr-client-transport) and [`NostrServerTransport`](./nostr-server-transport), handling the common logic for connecting to relays, managing subscriptions, and converting messages between the MCP and Nostr formats.
|
||||
The `BaseNostrTransport` is an abstract class that provides the core functionality for all Nostr-based transports in the `@contextvm/sdk`. It serves as the foundation for the [`NostrClientTransport`](../nostr-client-transport) and [`NostrServerTransport`](/transport/nostr-server-transport), handling the common logic for connecting to relays, managing subscriptions, and converting messages between the MCP and Nostr formats.
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
|
||||
@@ -16,7 +16,7 @@ We will build two separate scripts:
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- You have completed the [Quick Overview](/getting-started/quick-overview/).
|
||||
- You have completed the [Quick Overview](../getting-started/quick-overview/).
|
||||
- You have two Nostr private keys (one for the server, one for the client). You can generate new keys using various tools, or by running `nostr-tools` commands.
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user