How to Deploy Starlight Theme Documentation on GitHub Pages

While documenting a project using the Starlight Theme, I decided to host it on GitHub Pages. During deployment, I ran into a few challenges. This article walks through those issues and how I resolved them, hopefully helping anyone facing similar problems.

Prerequisites

• Node.js (version 18 or higher recommended)

• Git for version control

• A GitHub account

Step 1: Create a Starlight theme Project

To create a documentation site using the Starlight Theme, you will need to create a new project. This command will configure and create the necessary file for your project.

npm create astro@latest -- --template starlight

Run the following command to start the development server:

npm run dev

You should now see the default Starlight documentation site running at http://localhost:4321

You can deploy an Astro site to GitHub Pages by using GitHub Actions. GitHub Actions help you automate, build, test, and deploy your site from GitHub. To do this, your source code must be hosted on GitHub.

Step 2: Configure astro.config.mjs for GitHub Pages

Open the astro.config.mjs file and update it with your GitHub Pages settings:

import { defineConfig } from 'astro/config';

import starlight from '@astro-starlight/theme';


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

// https://astro.build/config
export default defineConfig({
    site: 'https://your-username.github.io',
    base: '/your-repo-name/',
    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' },
                },
            ],
        }),
    ],
});

Replace your-username and your-repo-name with your actual GitHub username and Repository name. The base property should match your repository name exactly.

Step 3: Create a GitHub Actions Workflow

Create the GitHub Actions workflow directory and a new file in your project .github/workflows/deploy.yml:

Paste in the YAML below in the deploy.yml file:

name: Deploy to GitHub Pages

on:
  # Trigger the workflow every time you push to the `main` branch
  # Using a different branch name? Replace `main` with your branch’s name
  push:
    branches: [ master ]
  # Allows you to run this workflow manually from the Actions tab on GitHub.
  workflow_dispatch:

# Allow this job to clone the repo and create a page deployment
permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout your repository using git
        uses: actions/checkout@v4
      - name: Install, build, and upload your site
        uses: withastro/action@v3
        # with:
          # path: . # The root location of your Astro project inside the repository. (optional)
          # node-version: 20 # The specific version of Node that should be used to build your site. Defaults to 20. (optional)
          # package-manager: pnpm@latest # The Node package manager that should be used to install dependencies and build your site. Automatically detected based on your lockfile. (optional)

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Step 4: Create and Configure Your GitHub Repository

• Go to GitHub and create a new repository.

• Make sure the repository name matches what you used in your astro.config.mjs file.

Step 5: Push to GitHub

Initialize git in your project directory and push to GitHub:

git init

git remote add origin https://github.com/your-username/your-repo-name.git

git add .

git commit -m "Initial commit"

git push -u origin main

Step 6: Enable GitHub Pages

• Go to your repository on GitHub

• Click Settings > Pages

• Under Build and Deployment, choose GitHub Actions as the Source of your site.

• Click Save.

• After the workflow finishes, your site will be live at:

Once finished, your site will be live at:

https://your-username.github.io/your-repo-name/

Conclusion

By following this comprehensive process, you’ll be able to successfully deploy your Starlight theme site to GitHub Pages. Whether you’re building a personal project, internal documentation, or an open-source site, this approach ensures your deployment is automated, reliable, and version-controlled. I hope this guide saves you time and helps you avoid the challenges I faced during deployment.

Happy Learning!!!