Starlight Notes

Installing Starlight

Install Node.js to get npm
```
node -v
```
Update npm to the latest version
```
npm -v
npm install -g npm@latest
```

Create a new Astro + Starlight project

npm create astro@latest -- --template starlight
npm warn "starlight" is being parsed as a normal command line argument.
npm warn Unknown cli config "--template". This will stop working in the next major version of npm.
Need to install the following packages:
create-astro@5.0.5
Ok to proceed? (y)
> npx
> create-astro starlight
dir Using starlight as project directory
How would you like to start your new project?
- A basic, helpful starter project (recommended)
- Use blog template
- Use docs (Starlight) template
- Use minimal (empty) template Unable to fetch latest astro version from the npm registry.  Using 6.1.2 instead.
Install dependencies? (recommended)
Initialize a new git repository? (optional)

cd starlight
npm run dev (q + Enter to stop)
Use astro add to add frameworks like react or tailwind

Updating Starlight

Update Starlight to the latest version
```
npx @astrojs/upgrade
```

Deploy to GitHub Pages (gh-pages branch)

Configure Starlight for GitHub Pages by adding site and base to astro.config.mjs:

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

// https://astro.build/config
export default defineConfig({
    site: 'https://username.github.io',
    base: '/my-repo',
    integrations: [
        starlight({
            title: 'My Docs',
            social: [{ icon: 'github', label: 'GitHub', href: 'https://github.com/withastro/starlight' }],
            sidebar: [
                {
                    label: 'Guides',
                    items: [
                        // Each item here is one entry in the navigation menu.
                        { label: 'Example Guide', slug: 'guides/example' },
                    ],
                },
                {
                    label: 'Reference',
                    autogenerate: { directory: 'reference' },
                },
            ],
        }),
    ],
});

Run npm run build to generate the dist/ folder
Create an empty file named dist/.nojekyll
(this tells GitHub Pages not to use Jekyll, which can break Astro/Starlight’s asset paths)
Deploy the contents of the dist/ folder to the gh-pages branch
- Remove dist/ from .gitignore
- git add dist && git commit -m "Update dist for deployment" && git push
- git subtree push --prefix dist origin gh-pages
Configure the GitHub Repository to deploy GitHub Pages from the gh-pages branch
- Go to GitHub > repository > Settings > Pages
- Under Build and deployment, select Deploy from a branch for Source
- Set the Branch to gh-pages and the folder to /(root)

Starlight Notes

Installing Starlight

Updating Starlight

Deploy to GitHub Pages (gh-pages branch)

Resources