Building a Documentation Site with Astro Starlight and Custom Expressive Code

Joe Klakus

Dec 12, 2025

1 min read

Introduction:

Astro Starlight is a beautiful, accessible documentation theme for Astro that makes building documentation sites a breeze. It comes with powerful features out of the box, including built-in search, responsive navigation, and excellent accessibility support. But what if you want to take your code blocks to the next level with expressive, visually stunning code presentations?

In this tutorial, we’ll build a documentation site from scratch using Astro Starlight and enhance it with custom expressive code blocks that include syntax highlighting, copy buttons, line numbers, and more.

Prerequisites

Before we begin, ensure you have:

• Node.js 18 or higher installed
• A package manager (we’ll use pnpm)
• Basic knowledge of Astro and Markdown

Step 1: Create a New Astro Starlight Project

Start by creating a new Astro project with the Starlight template:

pnpm create astro@latest my-docs --template starlight --yes
cd my-docs

This will set up a complete Astro project with Starlight pre-configured, including:

• Documentation pages in src/content/docs
• Blog section in src/content/blog
• Configuration files
• Default styling

Step 2: Explore the Project Structure

After installation, your project will look like this:

my-docs/
├── public/
├── src/
│   ├── assets/
│   ├── content/
│   │   ├── blog/
│   │   ├── config.ts
│   │   └── docs/
│   │       ├── getting-started.md
│   │       ├── reference.md
│   │       └── index.mdx
│   └── env.d.ts
├── astro.config.mjs
├── package.json
└── tsconfig.json

The src/content/docs directory is where you’ll create your documentation pages. Each Markdown file becomes a page in your documentation.

Step 3: Configure Your Documentation Site

Open src/content/config.ts to customize your site:

import { defineCollection, z } from 'astro:content';
import { docsSchema } from '@astrojs/starlight/schema';

const docs = defineCollection({ 
  schema: docsSchema({
    extend: z.object({
      authors: z.array(z.string()).optional(),
    })
  }) 
});

export const collections = { docs };

Update astro.config.mjs to configure Starlight:

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Documentation Site',
      description: 'Beautiful documentation built with Astro Starlight',
      social: {
        github: 'https://github.com/your-username/my-docs',
      },
      sidebar: [
        { label: 'Getting Started', link: '/getting-started' },
        { label: 'Reference', link: '/reference' },
      ],
      customCss: ['./src/styles/custom.css'],
    }),
  ],
});

Step 4: Deploy Your Documentation Site

Build and preview your documentation:

pnpm build
pnpm preview

For deployment, you can use various platforms:

• Vercel: Connect your GitHub repository and deploy automatically
• Netlify: Drag and drop your build output
• Cloudflare Pages: Use the GitHub integration
• GitHub Pages: Deploy via GitHub Actions

Advanced Features

Search Enhancement:

Starlight includes built-in search, but you can enhance it:

// astro.config.mjs
starlight({
  search: {
    indexLastUpdated: true,
    maxPreviewChars: 150,
  },
})

Multi-language Support:

starlight({
  locales: {
    en: {
      label: 'English',
      lang: 'en',
    },
    es: {
      label: 'Español',
      lang: 'es',
    },
  },
  defaultLocale: 'en',
})

Custom Theme Colors:

starlight({
  customCss: ['./src/styles/custom.css'],
})

/* custom.css */
:root {
  --sl-hue: 250; /* Purple theme */
  --sl-color-white: #ffffff;
  --sl-color-black: #1a1a1a;
}

Troubleshooting

Code blocks not rendering:

• Ensure all dependencies are installed
• Check that the component is properly exported
• Verify the MDX integration is configured correctly

Styling issues:

• Clear your browser cache
• Check for conflicting CSS in other components
• Verify CSS specificity

Build errors:

• Run pnpm build --verbose for detailed error messages
• Check that all imports are correct
• Verify TypeScript configurations

Best Practices

1. Organize Content: Structure your documentation logically with clear hierarchies
2. Use Examples: Provide code examples that users can copy and run
3. Keep Updated: Regularly update your documentation as your project evolves
4. Accessibility: Ensure all content meets WCAG guidelines (Starlight helps with this)
5. Versioning: Consider versioning your documentation for different releases

Conclusion

Building a documentation site with Astro Starlight and custom expressive code blocks gives you a powerful, beautiful platform for sharing knowledge. Starlight provides an excellent foundation with accessibility and performance built-in, while custom code components elevate the developer experience.

With this setup, you have full control over how your code is presented, making your documentation not just informative but also visually engaging and easy to use. Happy documenting!