Astro Starlight

https://github.com/withastro/starlight
Admin
Starlight is a documentation website framework for Astro, built to help you create beautiful and...
Tokens:82,524
Snippets:927
Trust Score:8.5
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install a theme with npm

Source: https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md

Install your theme in the StackBlitz demo project using npm.

```sh
npm i your-theme-name
```

--------------------------------

### Start the development server

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/getting-started.mdx

Start the Astro development server to preview your site locally. The npm, pnpm, and Yarn commands are equivalent alternatives shown in tabs.

```sh
npm run dev
```

```sh
pnpm dev
```

```sh
yarn dev
```

--------------------------------

### Run the dev server

Source: https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md

Start the development server to preview the theme.

```sh
npm run dev
```

--------------------------------

### Install Starlight Markdoc preset with pnpm

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/guides/authoring-content.mdx

Second step to add Markdoc to an existing Starlight site: install the Starlight Markdoc preset package.

```sh
pnpm add @astrojs/starlight-markdoc
```

--------------------------------

### Install Starlight Markdoc preset with Yarn

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/guides/authoring-content.mdx

Second step to add Markdoc to an existing Starlight site: install the Starlight Markdoc preset package.

```sh
yarn add @astrojs/starlight-markdoc
```

--------------------------------

### Install Starlight Markdoc preset with npm

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/guides/authoring-content.mdx

Second step to add Markdoc to an existing Starlight site: install the Starlight Markdoc preset package.

```sh
npm install @astrojs/starlight-markdoc
```

--------------------------------

### Install Starlight with pnpm

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/manual-setup.mdx

Run this command in your project's root directory to install Starlight and add it to the integrations array in your Astro config file.

```sh
pnpm astro add starlight
```

--------------------------------

### Install @astrojs/starlight-docsearch

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/guides/site-search.mdx

Install the official Starlight DocSearch plugin using your preferred package manager.

```sh
npm install @astrojs/starlight-docsearch
```

```sh
pnpm add @astrojs/starlight-docsearch
```

```sh
yarn add @astrojs/starlight-docsearch
```

--------------------------------

### File tree for Starlight subpath setup

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/manual-setup.mdx

Shows the required directory structure to serve Starlight pages under /guides/. Place all docs content in src/content/docs/guides/.

```markdown
<FileTree>

- src/
  - content/
    - docs/
      - **guides/**
        - guide.md
        - index.md
  - pages/
- astro.config.mjs

</FileTree>
```

--------------------------------

### Get all UI strings with Astro.locals.t.all()

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/guides/i18n.mdx

Use t.all() to retrieve an object containing all UI strings for the current locale. The comment shows a partial example of the returned object.

```astro
---
// src/components/Example.astro
const allStrings = Astro.locals.t.all();
//    ^
//    {
//      "skipLink.label": "Skip to content",
//      "search.label": "Search",
//      …
//    }
---
```

--------------------------------

### Install Starlight with npm

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/manual-setup.mdx

Run this command in your project's root directory to install Starlight and add it to the integrations array in your Astro config file.

```sh
npx astro add starlight
```

--------------------------------

### Type hook arguments with 'HookParameters' utility type for 'config:setup' hook

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/reference/plugins.md

Use the `HookParameters` utility type to type hook arguments. In this example, the `options` parameter is typed to match the arguments passed to the `config:setup` hook.

```ts
import type { HookParameters } from '@astrojs/starlight/types';

function configSetup(options: HookParameters['config:setup']) {
  options.useTranslations('en');
}
```

--------------------------------

### Install Starlight with Yarn

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/manual-setup.mdx

Run this command in your project's root directory to install Starlight and add it to the integrations array in your Astro config file.

```sh
yarn astro add starlight
```

--------------------------------

### Install Fontsource font with npm

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/guides/customization.mdx

Install the @fontsource/ibm-plex-serif package using npm. This is the second step in setting up a Fontsource font.

```sh
npm install @fontsource/ibm-plex-serif
```

--------------------------------

### Use Steps component in MDX

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/components/steps.mdx

MDX example showing how to use the Steps component to style a numbered list of tasks.

```mdx
import { Steps } from '@astrojs/starlight/components';

<Steps>

1. Import the component into your MDX file:

   ```js
   import { Steps } from '@astrojs/starlight/components';
   ```

2. Wrap `<Steps>` around your ordered list items.

</Steps>
```

--------------------------------

### Markdown code block showing JavaScript example

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/guides/authoring-content.mdx

Displays the JavaScript code block example as a Markdown code block, demonstrating how to include code blocks in documentation.

```markdown
```js
// Javascript code with syntax highlighting.
var fun = function lang(l) {
	dateformat.i18n = require('./lang/' + l);
	return true;
};
```
```

--------------------------------

### Use steps tag in Markdoc

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/components/steps.mdx

Markdoc example showing how to use the steps tag to style a numbered list of tasks.

```markdoc
{% steps %}

1. Import the component into your MDX file:

   ```js
   import { Steps } from '@astrojs/starlight/components';
   ```

2. Wrap `<Steps>` around your ordered list items.

{% /steps %}
```

--------------------------------

### docsLoader()

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/reference/configuration.mdx

Loads local Markdown, MDX, and Markdoc files from the `src/content/docs/` directory. File names starting with an underscore (`_`) are ignored.

```APIDOC
## docsLoader()

### Description
Loads local Markdown, MDX, and Markdoc files from the `src/content/docs/` directory. File names starting with an underscore (`_`) are ignored.

### Import
```js
import { docsLoader } from '@astrojs/starlight/loaders';
```

### Options

#### `generateId()`

**type:** `({ entry: string; base: URL; data: Record<string, unknown> }) => string`

By default, pages generated using `docsLoader()` process your file names using a sluggifier, which removes special characters and lowercases the file name. If you want to override this default, provide your own custom `generateId()` function.

For example, this can be useful to preserve special characters that would be removed. By default, `Example.File.md` would be served at `/examplefile`. If you wanted to serve it at `/Example.File`, you could do so by defining a custom `generateId()` function:

```js
docsLoader({
	// Remove the `.md` or `.mdx` extension, but otherwise don’t process filenames.
	generateId: ({ entry }) => entry.split('.').slice(0, -1).join('.'),
}),
```

See [`generateId()` in the Astro docs](https://docs.astro.build/en/reference/content-loader-reference/#generateid) for more details.
```

--------------------------------

### Example.astro: Access siteTitle from Astro.locals.starlightRoute

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/guides/route-data.mdx

Access the route data from Astro.locals.starlightRoute in an Astro component. The example destructures siteTitle to display the site title.

```astro
---
const { siteTitle } = Astro.locals.starlightRoute;
---

<p>The title of this site is “{siteTitle}”</p>

```

--------------------------------

### Pagefind UI translations JSON

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/guides/i18n.mdx

Example JSON file with translations for Pagefind UI strings using pagefind keys.

```json
{
	"pagefind.clear_search": "Clear",
	"pagefind.load_more": "Load more results",
	"pagefind.search_label": "Search this site",
	"pagefind.filters_label": "Filters",
	"pagefind.zero_results": "No results for [SEARCH_TERM]",
	"pagefind.many_results": "[COUNT] results for [SEARCH_TERM]",
	"pagefind.one_result": "[COUNT] result for [SEARCH_TERM]",
	"pagefind.alt_search": "No results for [SEARCH_TERM]. Showing results for [DIFFERENT_TERM] instead",
	"pagefind.search_suggestion": "No results for [SEARCH_TERM]. Try one of the following searches:",
	"pagefind.searching": "Searching for [SEARCH_TERM]..."
}
```

--------------------------------

### Set favicon path

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/reference/configuration.mdx

Example of setting the favicon option to a custom path.

```js
starlight({
  favicon: '/images/favicon.svg',
}),
```

--------------------------------

### Display an image using Markdown syntax

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/guides/authoring-content.mdx

Display an image in Markdown using the standard image syntax with alt-text. This example uses an external image URL.

```md
![An illustration of planets and stars featuring the word “astro”](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png)

```

--------------------------------

### Configure root locale

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/reference/configuration.mdx

Serves the default language without a `/lang/` directory by using the `root` key. The example shows English at the root and French under `/fr/`.

```js
starlight({
	locales: {
		root: {
			label: 'English',
			lang: 'en',
		},
		fr: {
			label: 'Français',
		},
	},
});
```

--------------------------------

### Get text direction with Astro.locals.t.dir()

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/guides/i18n.mdx

Use t.dir() to get the text direction of the current or a specific locale. The comments show example return values.

```astro
---
// src/components/Example.astro
const currentDirection = Astro.locals.t.dir();
//    ^
//    'ltr'
const arabicDirection = Astro.locals.t.dir('ar');
//    ^
//    'rtl'
---
```

--------------------------------

### Use absolutePathToLang() to get language and translate UI strings

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/reference/plugins.md

Example of using absolutePathToLang() to determine the language of a file from its absolute path, then using useTranslations() to get UI strings for that language. The Starlight configuration shows locales with English and French. The plugin logs a built-in UI string for French, and the output shows the logged message.

```js
starlight({
  title: 'My Docs',
  defaultLocale: 'en',
  locales: {
    // English docs in `src/content/docs/en/`
    en: { label: 'English' },
    // French docs in `src/content/docs/fr/`
    fr: { label: 'Français', lang: 'fr' },
  },
});
```

```ts
// plugin.ts
export default {
  name: 'plugin-use-translations',
  hooks: {
    'config:setup'({ absolutePathToLang, useTranslations, logger }) {
      const lang = absolutePathToLang(
        '/absolute/path/to/project/src/content/docs/fr/index.mdx'
      );
      const t = useTranslations(lang);
      logger.info(t('aside.tip'));
    },
  },
};
```

```shell
[plugin-use-translations] Astuce
```

--------------------------------

### Set up local development environment

Source: https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md

Steps to set up a local development environment: clone your fork, change into the repo directory, install dependencies with pnpm, and generate TypeScript types for Astro modules. Requires Node.js v22.13.0+ and pnpm.

```sh
git clone https://github.com/YOUR-USERNAME/starlight.git
```

```sh
cd starlight
```

```sh
pnpm i
```

```sh
cd docs
pnpm astro sync
```

--------------------------------

### Use useTranslations() in a Starlight plugin

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/reference/plugins.md

Example of using the useTranslations() helper in a Starlight plugin's config:setup hook. It logs a built-in UI string for the Simplified Chinese language. The output shows the logged message.

```ts
// plugin.ts
export default {
  name: 'plugin-use-translations',
  hooks: {
    'config:setup'({ useTranslations, logger }) {
      const t = useTranslations('zh-CN');
      logger.info(t('builtWithStarlight.label'));
    },
  },
};
```

```shell
[plugin-use-translations] 基于 Starlight 构建
```

--------------------------------

### File structure for adding pages

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/guides/pages.mdx

Create .md or .mdx files in src/content/docs/ to generate pages. Sub-folders create multiple path segments. This structure generates pages at example.com/hello-world and example.com/reference/faq.

```text
- src/
  - content/
    - docs/
      - hello-world.md
      - reference/
        - faq.md
```

--------------------------------

### logger: Log a message with plugin name prefix

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/reference/plugins.md

Shows how to use the logger instance to write logs. All logged messages are prefixed with the plugin name. The example logs 'Starting long process…' and the output shows the prefixed message.

```ts
// plugin.ts
export default {
  name: 'long-process-plugin',
  hooks: {
    'config:setup'({ logger }) {
      logger.info('Starting long process…');
      // Some long process…
    },
  },
};
```

```shell
[long-process-plugin] Starting long process…
```

--------------------------------

### Import and render a component in MDX

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/components/using-components.mdx

Shows how to import a component in an MDX file and render it as a JSX tag. The component name must start with an uppercase letter matching the import. Includes an example of a custom component with nested content.

```mdx
---
# src/content/docs/example.mdx
title: Welcome to my docs
---

import { Icon } from '@astrojs/starlight/components';
import CustomCard from '../../components/CustomCard.astro';

<Icon name="open-book" />

<CustomCard>Components can also contain **nested content**.</CustomCard>
```

--------------------------------

### Run the Astro dev server on the docs site

Source: https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md

Move into the `docs/` directory and run `pnpm dev` to start the dev server. You can then open http://localhost:4321 to see your changes. Changes to the Starlight integration require restarting the dev server.

```sh
cd docs
pnpm dev
```

--------------------------------

### Build the docs site with the packaged version of Starlight

Source: https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md

Run `pnpm build:dist` from the `docs/` directory to ensure the docs site builds successfully with the packaged version of Starlight.

```sh
cd docs
pnpm build:dist
```

--------------------------------

### Create a new Starlight Markdoc project

Source: https://github.com/withastro/starlight/blob/main/examples/markdoc/README.md

Scaffolds a new Starlight project using the Markdoc starter template. Run this command in a terminal to create a project with Markdoc support.

```bash
npm create astro@latest -- --template starlight/markdoc
```

--------------------------------

### Install Fontsource font with Yarn

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/guides/customization.mdx

Install the @fontsource/ibm-plex-serif package using Yarn. This is the second step in setting up a Fontsource font.

```sh
yarn add @fontsource/ibm-plex-serif
```

--------------------------------

### Create a new Starlight project

Source: https://github.com/withastro/starlight/blob/main/examples/basics/README.md

Run this command to scaffold a new Starlight project using the official template.

```bash
npm create astro@latest -- --template starlight
```

--------------------------------

### Install Fontsource font with pnpm

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/guides/customization.mdx

Install the @fontsource/ibm-plex-serif package using pnpm. This is the second step in setting up a Fontsource font.

```sh
pnpm add @fontsource/ibm-plex-serif
```

--------------------------------

### Create a new Starlight project with Markdoc using pnpm

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/guides/authoring-content.mdx

Use this command to scaffold a new Starlight project with Markdoc pre-configured via the create astro CLI.

```sh
pnpm create astro --template starlight/markdoc
```

--------------------------------

### Create Starlight Tailwind Project

Source: https://github.com/withastro/starlight/blob/main/examples/tailwind/README.md

Run this command in your terminal to initialize a new Starlight project with the Tailwind CSS template.

```bash
npm create astro@latest -- --template starlight/tailwind
```

--------------------------------

### Basic FileTree usage in MDX

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/components/file-tree.mdx

Demonstrates the basic usage of the `<FileTree>` component in MDX with an unordered markdown list. Sub-directories are created via nested lists or by appending a `/` to list items.

```mdx
import { FileTree } from '@astrojs/starlight/components';

<FileTree>

- astro.config.mjs
- package.json
- src
  - components
    - Header.astro
    - Title.astro
  - pages/

</FileTree>
```

--------------------------------

### Configurar enlaces de edición con editLink.baseUrl

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/es/guides/customization.mdx

Configura `editLink.baseUrl` para habilitar el enlace "Editar página" en el pie de cada página. El valor se añade al inicio de la ruta de la página actual para formar el enlace de edición completo. Este ejemplo usa el subdirectorio `docs/` en la rama `main` del repositorio `withastro/starlight` en GitHub.

```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
	integrations: [
		starlight({
			title: 'Docs Con Enlaces De Edición',
			editLink: {
				baseUrl: 'https://github.com/withastro/starlight/edit/main/docs/',
			},
		}),
	],
});
```

--------------------------------

### Set up route data middleware with defineRouteMiddleware

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/guides/route-data.mdx

Steps to set up a route data middleware: create a file exporting an onRequest function using defineRouteMiddleware, register it in astro.config.mjs via the routeMiddleware option, then modify route data using the context argument. The context contains locals.starlightRoute with the content collection entry.

```ts
// src/routeData.ts
import { defineRouteMiddleware } from '@astrojs/starlight/route-data';

export const onRequest = defineRouteMiddleware(() => {});
```

```js
// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
	integrations: [
		starlight({
			title: 'My delightful docs site',
			routeMiddleware: './src/routeData.ts',
		}),
	],
});
```

```ts
// src/routeData.ts
import { defineRouteMiddleware } from '@astrojs/starlight/route-data';

export const onRequest = defineRouteMiddleware((context) => {
	// Get the content collection entry for this page.
	const { entry } = context.locals.starlightRoute;
	// Update the title to add an exclamation mark.
	entry.data.title = entry.data.title + '!';
});
```

--------------------------------

### Install @astrojs/starlight-tailwind

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/guides/css-and-tailwind.mdx

Install the Starlight Tailwind compatibility package using your package manager. This package provides the complementary CSS needed for Tailwind to work with Starlight.

```sh
npm install @astrojs/starlight-tailwind
```

```sh
pnpm add @astrojs/starlight-tailwind
```

```sh
yarn add @astrojs/starlight-tailwind
```

--------------------------------

### Import Tabs and TabItem components

Source: https://github.com/withastro/starlight/blob/main/packages/starlight/__e2e__/fixtures/basics/src/content/docs/tabs-nested.mdx

Import the Tabs and TabItem components from the Starlight components package. The example shows a set of tabs using the 'pkg' sync key with nested tabs using an 'os' sync key, demonstrating how to synchronize tab selections across different levels.

```javascript
import { Tabs, TabItem } from '@astrojs/starlight/components';
```

```html
<Tabs syncKey="pkg">

    <TabItem label="npm">

    	npm content

    	<Tabs syncKey="os">
    		<TabItem label="macos">npm macOS</TabItem>
    		<TabItem label="windows">npm Windows</TabItem>
    		<TabItem label="linux">npm GNU/Linux</TabItem>
    	</Tabs>

    </TabItem>

    <TabItem label="pnpm">

    		pnpm content

    		<Tabs syncKey="os">
    				<TabItem label="macos">pnpm macOS</TabItem>
    				<TabItem label="windows">pnpm Windows</TabItem>
    				<TabItem label="linux">pnpm GNU/Linux</TabItem>
    			</Tabs>

    	</TabItem>

    <TabItem label="yarn">

    		yarn content

    		<Tabs syncKey="os">
    				<TabItem label="macos">yarn macOS</TabItem>
    				<TabItem label="windows">yarn Windows</TabItem>
    				<TabItem label="linux">yarn GNU/Linux</TabItem>
    			</Tabs>

    	</TabItem>

</Tabs>
```

--------------------------------

### Starlight plugin interface shape

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/reference/plugins.md

Defines the Starlight plugin structure with name and hooks, including optional i18n:setup and required config:setup hooks with their parameters.

```TypeScript
interface StarlightPlugin {
  name: string;
  hooks: {
    'i18n:setup'?: (options: {
      injectTranslations: (
        translations: Record<string, Record<string, string>>
      ) => void;
    }) => void | Promise<void>;
    'config:setup': (options: {
      config: StarlightUserConfig;
      updateConfig: (newConfig: StarlightUserConfig) => void;
      addIntegration: (integration: AstroIntegration) => void;
      addRouteMiddleware: (config: { entrypoint: string; order?: 'pre' | 'post' | 'default' }) => void;
      astroConfig: AstroConfig;
      command: 'dev' | 'build' | 'preview';
      isRestart: boolean;
      logger: AstroIntegrationLogger;
      useTranslations: (lang: string) => I18nT;
      absolutePathToLang: (path: string) => string;
    }) => void | Promise<void>;
  };
}
```

--------------------------------

### Create a Starlight project with npm, pnpm, or Yarn

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/components/steps.mdx

Commands to create a new Starlight project using npm, pnpm, or Yarn. These are shown as alternatives in tabs within the first step of the preview.

```sh
npm create astro@latest -- --template starlight
```

```sh
pnpm create astro --template starlight
```

```sh
yarn create astro --template starlight
```

--------------------------------

### Create a new Starlight project with Markdoc using Yarn

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/guides/authoring-content.mdx

Use this command to scaffold a new Starlight project with Markdoc pre-configured via the create astro CLI.

```sh
yarn create astro --template starlight/markdoc
```

--------------------------------

### Frontmatter example for a Starlight page

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/guides/pages.mdx

All Starlight pages share a customizable common set of frontmatter properties. This example shows the title and description properties. Starlight will warn if important properties are missing.

```markdown
---
title: Hello, World!
description: This is a page in my Starlight-powered site
---
```

--------------------------------

### Create markdoc.config.mjs with Starlight Markdoc preset

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/guides/authoring-content.mdx

Third step to add Markdoc to an existing Starlight site: create a Markdoc configuration file and use the Starlight Markdoc preset.

```js
import { defineMarkdocConfig } from '@astrojs/markdoc/config';
import starlightMarkdoc from '@astrojs/starlight-markdoc';

export default defineMarkdocConfig({
	extends: [starlightMarkdoc()],
});
```

--------------------------------

### Caution and danger asides example

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/guides/authoring-content.mdx

Shows caution and danger asides together. Caution asides draw attention to potential issues, while danger asides highlight serious warnings. The example includes a list inside the danger aside.

```markdown
:::caution
If you are not sure you want an awesome docs site, think twice before using [Starlight](/).
:::

:::danger
Your users may be more productive and find your product easier to use thanks to helpful Starlight features.

- Clear navigation
- User-configurable colour theme
- [i18n support](/guides/i18n/)

:::

```

--------------------------------

### Run unit tests with Vitest

Source: https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md

Move into the Starlight package and run `pnpm test` to run unit tests. This will run tests and then listen for changes, re-running tests when files change.

```sh
cd packages/starlight
pnpm test
```

--------------------------------

### Inject translations using 'injectTranslations' in the 'i18n:setup' hook

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/reference/plugins.md

The `i18n:setup` hook can be used to inject translation strings for different locales. The `injectTranslations` callback adds or updates translation strings used in Starlight's localization APIs.

```ts
// plugin.ts
export default {
  name: 'plugin-with-translations',
  hooks: {
    'i18n:setup'({ injectTranslations }) {
      injectTranslations({
        en: {
          'myPlugin.doThing': 'Do the thing',
        },
        fr: {
          'myPlugin.doThing': 'Faire le truc',
        },
      });
    },
  },
};
```

--------------------------------

### CardGrid Component

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/components/card-grids.mdx

Documentation for the CardGrid component, including its import, props, and usage examples.

```APIDOC
## [COMPONENT] CardGrid

### Description
Wraps multiple Card or LinkCard components in a responsive grid layout.

### Import
```tsx
import { CardGrid } from '@astrojs/starlight/components';
```

### Props
#### `stagger`
- **type:** `boolean`
- **Required:** No
- **Description:** Defines whether to stagger the cards in the grid or not.

### Usage Examples
#### Group cards
```mdx
import { Card, CardGrid } from '@astrojs/starlight/components';

<CardGrid>
	<Card title="Check this out" icon="open-book">
		Interesting content you want to highlight.
	</Card>
	<Card title="Other feature" icon="information">
		More information you want to share.
	</Card>
</CardGrid>
```

#### Group link cards
```mdx
import { LinkCard, CardGrid } from '@astrojs/starlight/components';

<CardGrid>
	<LinkCard title="Authoring Markdown" href="/guides/authoring-content/" />
	<LinkCard title="Components" href="/components/using-components/" />
</CardGrid>
```

#### Stagger cards
```mdx
import { Card, CardGrid } from '@astrojs/starlight/components';

<CardGrid stagger>
	<Card title="Check this out" icon="open-book">
		Interesting content you want to highlight.
	</Card>
	<Card title="Other feature" icon="information">
		More information you want to share.
	</Card>
</CardGrid>
```
```

--------------------------------

### Create a new Starlight project with Tailwind CSS

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/guides/css-and-tailwind.mdx

Use the package manager of your choice to scaffold a new Starlight project with Tailwind CSS pre-configured. The template is starlight/tailwind.

```sh
npm create astro@latest -- --template starlight/tailwind
```

```sh
pnpm create astro --template starlight/tailwind
```

```sh
yarn create astro --template starlight/tailwind
```

--------------------------------

### `<Aside>` Component

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/components/asides.mdx

Documentation for the Starlight `<Aside>` component, including its import, usage, props, and examples.

```APIDOC
## `<Aside>` Component

### Description
Displays secondary information alongside a page's main content. The component supports optional `type`, `title`, and `icon` attributes to control its appearance.

### Import
```tsx
import { Aside } from '@astrojs/starlight/components';
```

### Usage
```mdx
<Aside>Some content in an aside.</Aside>
<Aside type="caution">Some cautionary content.</Aside>
<Aside type="tip">Other content is also supported in asides.</Aside>
<Aside type="danger">Do not give your password to anyone.</Aside>
```

### Props

#### `type`
- **type:** `'note' | 'tip' | 'caution' | 'danger'`
- **default:** `'note'`
- The type of aside to display. Controls the aside's color, icon, and default title.

#### `title`
- **type:** `string`
- The title of the aside to display. If not set, the default title for the current aside `type` is used.

#### `icon`
- **type:** `StarlightIcon`
- The name of one of Starlight's built-in icons to override the default icon.

### Examples

#### Custom title
```mdx
<Aside type="caution" title="Watch out!">A warning aside *with* a custom title.</Aside>
```

#### Custom icon
```mdx
<Aside type="tip" icon="starlight">A tip aside *with* a custom icon.</Aside>
```
```

--------------------------------

### i18nLoader()

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/reference/configuration.mdx

Loads local JSON and YAML files from the `src/content/i18n/` directory. File names starting with an underscore (`_`) are ignored.

```APIDOC
## i18nLoader()

### Description
Loads local JSON and YAML files from the `src/content/i18n/` directory. File names starting with an underscore (`_`) are ignored.

### Import
```js
import { i18nLoader } from '@astrojs/starlight/loaders';
```

### Options

There are currently no options to configure `i18nLoader()`.
```

--------------------------------

### Project File Structure

Source: https://github.com/withastro/starlight/blob/main/examples/tailwind/README.md

Overview of the directory layout for an Astro + Starlight project.

```text
.
├── public/
├── src/
│   ├── assets/
│   ├── content/
│   │   └── docs/
│   ├── styles/
│   │   └── global.css
│   └── content.config.ts
├── astro.config.mjs
├── package.json
└── tsconfig.json
```

--------------------------------

### StarlightPlugin Interface

Source: https://github.com/withastro/starlight/blob/main/docs/src/content/docs/reference/plugins.md

The StarlightPlugin interface defines the structure of a Starlight plugin, including its name and hooks for setup and internationalization.

```APIDOC
## StarlightPlugin Interface

### Description
Defines the structure of a Starlight plugin, including its name and hooks for setup and internationalization.

### Properties
- **name** (string) - Required - The name of the plugin.
- **hooks** (object) - Required - An object containing plugin hooks.

### Hooks

#### `'i18n:setup'`
- **Type**: `(options: { injectTranslations: (translations: Record<string, Record<string, string>>) => void; }) => void | Promise<void>`
- **Description**: Optional hook for setting up internationalization translations.

#### `'config:setup'`
- **Type**: `(options: { config: StarlightUserConfig; updateConfig: (newConfig: StarlightUserConfig) => void; addIntegration: (integration: AstroIntegration) => void; addRouteMiddleware: (config: { entrypoint: string; order?: 'pre' | 'post' | 'default' }) => void; astroConfig: AstroConfig; command: 'dev' | 'build' | 'preview'; isRestart: boolean; logger: AstroIntegrationLogger; useTranslations: (lang: string) => I18nT; absolutePathToLang: (path: string) => string; }) => void | Promise<void>`
- **Description**: Required hook for customizing Starlight configuration, adding integrations, and more.

### Hook Parameters

#### `'i18n:setup'` Options
- **injectTranslations** (function) - Required - A function to inject translations.

#### `'config:setup'` Options
- **config** (StarlightUserConfig) - Required - The current Starlight user configuration.
- **updateConfig** (function) - Required - A function to update the Starlight configuration.
- **addIntegration** (function) - Required - A function to add an Astro integration.
- **addRouteMiddleware** (function) - Required - A function to add route middleware.
- **astroConfig** (AstroConfig) - Required - The current Astro configuration.
- **command** ('dev' | 'build' | 'preview') - Required - The current command being run.
- **isRestart** (boolean) - Required - Whether the dev server is restarting.
- **logger** (AstroIntegrationLogger) - Required - A logger instance for the integration.
- **useTranslations** (function) - Required - A function to get translations for a language.
- **absolutePathToLang** (function) - Required - A function to convert an absolute path to a language code.

### Example
```ts
interface StarlightPlugin {
  name: string;
  hooks: {
    'i18n:setup'?: (options: {
      injectTranslations: (
        translations: Record<string, Record<string, string>>
      ) => void;
    }) => void | Promise<void>;
    'config:setup': (options: {
      config: StarlightUserConfig;
      updateConfig: (newConfig: StarlightUserConfig) => void;
      addIntegration: (integration: AstroIntegration) => void;
      addRouteMiddleware: (config: { entrypoint: string; order?: 'pre' | 'post' | 'default' }) => void;
      astroConfig: AstroConfig;
      command: 'dev' | 'build' | 'preview';
      isRestart: boolean;
      logger: AstroIntegrationLogger;
      useTranslations: (lang: string) => I18nT;
      absolutePathToLang: (path: string) => string;
    }) => void | Promise<void>;
  };
}
```
```
Tokens:
Raw