🗂️

Starlight File Explorer

Explore and document files and folders in your Starlight site with an interactive file explorer.

Directorypublic
- favicon.svg
Directorysrc
- Directoryassets
  - logo.svg
  - screenshot.jpg
- Directorycomponents
  - CustomButton.astro
  - InteractiveWidget.jsx
- Directorycontent
  - Directorydocs
    - index.mdx
- content.config.ts
astro.config.mjs
package.json
tsconfig.json

public/favicon.svg

Default favicon

The default favicon for your website. The favicon can be configured using Starlight’s favicon configuration option.

The following example configures the public/images/favicon.svg file as the favicon for your documentation site.

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

Reference

src/assets/logo.svg

Site logo

A logo image to show in the navigation bar alongside or instead of the site title.

Add the path to your logo as Starlight’s logo.src option in astro.config.mjs:

starlight({
  logo: {
    src: './src/assets/logo.svg',
  },
})

Reference

src/assets/screenshot.jpg

Image used in a page

Images in Starlight use Astro’s built-in optimized asset support.

Markdown and MDX support the Markdown syntax for displaying images that includes alt-text for screen readers and assistive technology. Relative image paths are also supported for images stored locally in your project, e.g. from src/content/docs/index.mdx:

![A screenshot of the project](../../assets/screenshot.jpg)

Reference

src/components/CustomButton.astro

Astro component

Astro components are the basic building blocks of any Astro project. They use the .astro file extension.

You can use a component by importing it into your MDX file and then rendering it as a JSX tag. These look like HTML tags but start with an uppercase letter matching the name in your import statement, e.g. in src/content/docs/index.mdx:

import CustomButton from '../../components/CustomButton.astro';

<CustomButton>Get started</CustomButton>

Reference

src/components/InteractiveWidget.jsx

UI framework component

React

Astro supports a variety of popular frameworks including React, Preact, Svelte, Vue, SolidJS, and AlpineJS with official integrations. You can also find even more community-maintained framework integrations (e.g. Angular, Qwik, Elm).

A framework component can be made interactive (hydrated) using a client:* directive. These are component attributes that determine when your component’s JavaScript should be sent to the browser. For example, in src/content/docs/index.mdx:

import InteractiveWidget from '../../components/InteractiveWidget.jsx';

{/* This component's JS will begin importing when the page loads */}
<InteractiveWidget client:load />

Reference

src/content/docs/index.mdx

Home page

The index.mdx file at the root of src/content/docs/ generates the home page of your documentation site.

You can customize individual Markdown and MDX pages in Starlight by setting values in their frontmatter. Set template to 'splash' to use a wider layout without any sidebars designed for landing pages, and use hero to add a hero component to the top of the page:

---
title: My Home Page
template: splash
hero:
  tagline: Take your stuff to the moon and back in the blink of an eye.
  image:
    alt: A glittering, brightly colored logo
    file: ../../assets/logo.svg
  actions:
    - text: Tell me more
      link: /getting-started/
      icon: right-arrow
---

Reference

src/content.config.ts

Content collections configuration file

Astro content collections are used by Starlight to manage and organize your content files. All of your build-time content collections are configured in a special src/content.config.ts file.

The example below shows a typical content.config.ts file for a Starlight project.

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() }),
};

Reference

astro.config.mjs

Astro configuration file

The Astro configuration file which also includes the Starlight integration and configuration.

The example below shows a basic configuration for an Astro project using the Starlight integration.

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
    }),
  ],
});

Astro configuration

Starlight configuration

package.json

Project manifest

A file used by JavaScript package managers to manage your dependencies. It also defines the scripts that are commonly used to run Astro (ex: npm run dev, npm run build).

The example below shows a typical package.json file for a Starlight project.

{
  "name": "@example/starlight-basics",
  "type": "module",
  "version": "0.0.1",
  "private": true,
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro"
  },
  "dependencies": {
    "@astrojs/starlight": "^0.42.4",
    "astro": "^7.2.10",
    "sharp": "^0.35.3"
  }
}

Reference

tsconfig.json

TypeScript configuration file

A file containing all TypeScript configuration options for your Astro project.

The example below shows a typical tsconfig.json file for an Astro project.

{
  "extends": "astro/tsconfigs/strict",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"]
}

Reference