Configuration — astro.config.mjs

This file lives in the root folder of your project. Think of it as the main brain of your Astro Docus site. Every global setting — your site title, logo, sidebar, social links, deployment target — is controlled from here.

If you only ever edit one file, this is the one.

Full Code

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

export default defineConfig({
  site: 'https://astrodoc.pages.dev',
  output: 'static',
  adapter: cloudflare({
    imageService: 'passthrough',
  }),
  integrations: [
    starlight({
      title: 'Astro Docus',
      description: 'Starlight Astro documentation template with blog, landing, and pricing - JSON driven, MDX ready.',
      logo: {
        src: './src/assets/astrologos.png',
        replacesTitle: false,
      },
      components: {
        ThemeProvider: './src/components/ThemeProvider.astro',
      },
      customCss: ['./src/styles/base.css'],
      tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 3 },
      social: [
        {
          icon: 'github',
          label: 'GitHub',
          href: 'https://www.fiverr.com/creativitas',
        },
      ],
      sidebar: [
        {
          label: 'Get Started',
          items: [
            { label: 'Introduction', link: '/getstart/' },
            { label: 'Download', link: '/getstart/download/' },
            { label: 'Folder Structure', link: '/getstart/structure/' },
            { label: 'Installation', link: '/getstart/installation/' },
            { label: 'Configuration', link: '/getstart/configuration/' },
            { label: 'Article & MDX', link: '/getstart/article/' },
            { label: 'Gallery', link: '/getstart/gallery/' },
            { label: 'Blog System', link: '/getstart/blog/' },
            { label: 'Widget', link: '/getstart/widget/' },
            { label: 'Github Repo', link: '/getstart/github/' },
            { label: 'Hosting & Deploy', link: '/getstart/deploy-hosting/' },
            { label: 'Headless CMS', link: '/getstart/headlesscms/' },
          ],
        },
        {
          label: 'Headless CMS',
          autogenerate: { directory: 'cms' },
        },
        {
          label: 'Hosting Deploy',
          autogenerate: { directory: 'hosting' },
        },
        {
          label: 'Our Services',
          autogenerate: { directory: 'services' },
        },
        {
          label: 'Navigation',
          items: [
            { label: 'Home Page', link: '/' },
            { label: 'Blog Page', link: '/blog/' },
            { label: 'Pricing Plan', link: '/order/' },
          ],
        },
      ],
    }),
  ],
});

Breakdown

1. Imports

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

What it does:

defineConfig — Astro helper that gives you autocomplete and type checking.
starlight — The documentation framework that powers your docs theme.
cloudflare — The adapter that prepares your site for Cloudflare Pages.

What to use for other hosts:

Host	Import
Cloudflare	`import cloudflare from '@astrojs/cloudflare';`
Vercel	`import vercel from '@astrojs/vercel/static';`
Netlify	`import netlify from '@astrojs/netlify';`
GitHub Pages	Remove the adapter import entirely

2. Site

site: 'https://astrodoc.pages.dev',

What it does:

Defines the main domain of your site.
Used for SEO, sitemap generation, and canonical URLs.

Must change: Replace it with your own domain.

site: 'https://yourdomain.com',

If you deploy to Cloudflare Pages without a custom domain, your URL will look like https://your-project.pages.dev.

3. Output

output: 'static',

What it does:

Tells Astro to generate plain HTML files.
Faster, cheaper, and easier to host than server-rendered output.

Recommendation: Keep it as 'static'. Only change this if you need server-side rendering (SSR).

4. Adapter

adapter: cloudflare({
  imageService: 'passthrough',
}),

What it does:

Connects Astro to your hosting provider.
imageService: 'passthrough' means images are served as-is, without optimization.

What to use per host:

Host	Adapter block
Cloudflare	`cloudflare({ imageService: 'passthrough' })`
Vercel	`vercel()`
Netlify	`netlify()`
GitHub Pages	Remove the entire adapter block
Firebase	Remove the entire adapter block

5. Title & Description

title: 'Astro Docus',
description: 'Starlight Astro documentation template with blog, landing, and pricing - JSON driven, MDX ready.',

What it does:

title — Appears in the docs header and browser tab.
description — Used as the SEO meta description.

Change both to match your own brand.

6. Logo

logo: {
  src: './src/assets/astrologos.png',
  replacesTitle: false,
},

What it does:

src — Path to your logo file inside src/assets/.
replacesTitle — Controls whether the logo replaces the title text.
- false → Show logo + title
- true → Show logo only

Tip: Keep your logo around 40px tall for best results.

7. Components

components: {
  ThemeProvider: './src/components/ThemeProvider.astro',
},

What it does:

Overrides Starlight’s default components with your own.
In this case, ThemeProvider controls the dark/light mode toggle.

Recommendation: Do not change unless you have a custom component ready.

8. Custom CSS

customCss: ['./src/styles/base.css'],

What it does:

Loads your own CSS on top of Starlight’s defaults.
Edit src/styles/base.css to change colors, fonts, spacing, and more.

Tip: You can add multiple CSS files here — they load in order.

customCss: ['./src/styles/base.css', './src/styles/custom.css'],

9. Table of Contents

tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 3 },

What it does:

Controls the right-side Table of Contents on each docs page.
minHeadingLevel: 2 → Start from ## (H2).
maxHeadingLevel: 3 → Stop at ### (H3).

Examples:

Setting	Result
`{ min: 2, max: 3 }`	Shows H2 and H3 (default, recommended)
`{ min: 2, max: 4 }`	Shows H2, H3, and H4 (more detailed)
`{ min: 3, max: 4 }`	Shows only H3 and H4 (skips H2)

social: [
  {
    icon: 'github',
    label: 'GitHub',
    href: 'https://www.fiverr.com/creativitas',
  },
],

What it does:

Adds social icons in the top-right header.
icon — Name of a built-in Starlight icon (e.g., github, x.com, discord, blueSky, email).
label — Tooltip text shown on hover.
href — The URL the icon links to.

You can add multiple items:

social: [
  { icon: 'github', label: 'GitHub', href: 'https://github.com/yourname' },
  { icon: 'x.com', label: 'X', href: 'https://x.com/yourname' },
  { icon: 'discord', label: 'Discord', href: 'https://discord.gg/yourserver' },
],

{
  label: 'Get Started',
  items: [
    { label: 'Introduction', link: '/getstart/' },
    { label: 'Installation', link: '/getstart/installation/' },
  ],
},

What it does:

Creates a manual list of sidebar links.
label — The group title shown in the sidebar.
items — An array of individual links.

How links work:

The link must match the file path inside src/content/docs/.

File path	Link
`src/content/docs/getstart/index.md`	`/getstart/`
`src/content/docs/getstart/installation.md`	`/getstart/installation/`
`src/content/docs/cms/cloudcannon.md`	`/cms/cloudcannon/`

Order matters — the sidebar will display items in the exact order you list them.

{
  label: 'Headless CMS',
  autogenerate: { directory: 'cms' },
},

What it does:

Automatically reads every file inside src/content/docs/cms/ and adds them to the sidebar.
Alphabetical order by default.

When to use it:

When you have many files in a folder and don’t want to maintain a manual list.
When you want the sidebar to update automatically as you add new files.

Difference between manual and autogenerate:

Manual	Autogenerate
Full control over order	Alphabetical order
Must update when adding files	Updates automatically
Good for structured tutorials	Good for reference sections

{
  label: 'Navigation',
  items: [
    { label: 'Home Page', link: '/' },
    { label: 'Blog Page', link: '/blog/' },
    { label: 'Pricing Plan', link: '/order/' },
  ],
},

What it does:

Adds links to the main site (not just the docs).
Useful for jumping between docs, blog, and landing pages.

Common link targets:

Link	Destination
`/`	Homepage
`/blog/`	Blog listing
`/order/`	Pricing / order page
`/about/`	About page

Starlight lets you customize the sidebar further. Here are the most useful options.

By default, the sidebar appears on the left. To move it to the right, add this to the Starlight config:

starlight({
  // ...other options
  // Sidebar is left by default; Starlight does not natively support right-side
  // sidebar without CSS overrides.
})

Note: Starlight does not support a right-side sidebar out of the box. To move it, you must override CSS in src/styles/base.css:

/* Example: move sidebar to the right */
.sidebar {
  order: 2;
}
.main-frame {
  order: 1;
}

To make a sidebar group collapsed by default:

{
  label: 'Advanced',
  collapsed: true,
  items: [
    { label: 'Deep Dive', link: '/advanced/deep-dive/' },
  ],
},

Badges

Add visual badges next to sidebar items:

{
  label: 'New Feature',
  link: '/features/new/',
  badge: { text: 'New', variant: 'tip' },
},

Available variants: note, tip, caution, danger, success, default.

Starlight supports icons from Starlight Icons. Common ones:

github
x.com
discord
blueSky
email
rss
mastodon

Quick Reference

Setting	Purpose	Change?
`site`	Your domain	✅ Yes
`output`	Rendering mode	❌ Keep `static`
`adapter`	Hosting provider	✅ Yes (per host)
`title`	Site title	✅ Yes
`description`	SEO description	✅ Yes
`logo.src`	Logo path	✅ Yes
`logo.replacesTitle`	Logo vs title	Optional
`customCss`	Stylesheet path	Optional
`tableOfContents`	TOC heading levels	Optional
`social`	Header icons	✅ Yes
`sidebar`	Left navigation	✅ Yes

Final Notes

Always run npm run dev after editing astro.config.mjs to preview changes.
If the site fails to start, check the terminal for syntax errors — a missing comma or bracket will break everything.
Keep a backup of this file before making large changes.

You now understand every part of astro.config.mjs. This is the file that shapes your entire documentation site — treat it well.

Configuration — astro.config.mjs