Getting Started

Astro Starlight theme with Hack Club branding — for building beautiful docs and playgrounds

Prerequisites

You will need to have a Starlight website set up. If you don’t have one yet, you can follow the “Getting Started” guide in the Starlight docs to create one.

Installation

1. hc-starlight is a Starlight plugin. Install it by running the following command in your terminal:

   npm

   npm install hc-starlight

   pnpm

   pnpm add hc-starlight

   Yarn

   yarn add hc-starlight

2. Configure the plugin in your Starlight configuration in the astro.config.mjs file.

   astro.config.mjs

   import starlight from '@astrojs/starlight'
   import { defineConfig } from 'astro/config'
   import hcStarlight from 'hc-starlight'
   
   export default defineConfig({
     integrations: [
       starlight({
         plugins: [hcStarlight()],
         title: 'My Docs',
       }),
     ],
   })

3. Start the development server to preview the theme in action.

Options

hcSocial

Add Hack Club social links (icons) to the site by passing an array of objects to the hcSocial option. Each item should include icon (a key from HC Starlight’s icon set or the special string "hackclub"), href, and an optional label:

import hcStarlight from "hc-starlight";
// ---cut---
hcStarlight({
  hcSocial: [
    { icon: "github", href: "https://github.com/hackclub", label: "GitHub" },
    { icon: "hackclub", href: "https://hackclub.com", label: "Hack Club" },
  ],
});

See the full list of icons provided by HC Starlight on the Icons reference page: Icons reference. These are normalized versions of some of the @hackclub/icons.

If you prefer to use Starlight’s built-in icons instead, keep using the default social field in Starlight’s config—see Starlight’s social configuration: https://starlight.astro.build/reference/configuration/#social

withClientRouting

Control whether Starlight client routing is enabled for a smoother SPA-like navigation experience. withClientRouting accepts either a boolean or an object to configure behavior:

Default: true.

// Enable simple client routing
hcStarlight({
  withClientRouting: true,
});

This theme uses the astro-vtbot package for client routing. See the guide: https://events-3bg.pages.dev/jotter/starlight/guide/

Or configure the routing behavior using an object:

hcStarlight({
  withClientRouting: {
    active: true,
    animate: "fade", // 'fade' | 'slide' | 'initial' | 'none'
    fallback: "swap", // 'animate' | 'swap' | 'none'
  },
});

The object form allows finer control over which client-side routing features are active and how transitions behave.