Customizing Starlight

Starlight provides sensible default styling and features, so you can get started quickly with no configuration needed. When you want to start customizing the look and feel of your Starlight site, this guide has you covered.

Add your logo

Adding a custom logo to the site header is a quick way to add your individual branding to a Starlight site.

By default, the logo will be displayed alongside your site’s title. If your logo image already includes the site title, you can visually hide the title text by setting the replacesTitle option. The title text will still be included for screen readers so that the header remains accessible.

starlight({
  title: 'Docs With My Logo',
  logo: {
    src: './src/assets/my-logo.svg',
    replacesTitle: true,
  },
}),

Light and dark logo variants

You can display different versions of your logo in light and dark modes.

Enable sitemap

Starlight has built-in support for generating a sitemap. Enable sitemap generation by setting your URL as site in astro.config.mjs:

astro.config.mjs

export default defineConfig({
  site: 'https://stargazers.club',
  integrations: [starlight({ title: 'Site with sitemap' })],
});

Learn how to add a sitemap link to robots.txt in the Astro Docs.

Page layout

By default, Starlight pages use a layout with a global navigation sidebar and a table of contents that shows the current page headings.

You can apply a wider page layout without sidebars by setting template: splash in a page’s frontmatter. This works particularly well for landing pages and you can see it in action on the homepage of this site.

src/content/docs/index.md

---
title: My Landing Page
template: splash
---

Table of contents

Starlight displays a table of contents on each page to make it easier for readers to jump to the heading they are looking for. You can customize — or even disable — the table of contents globally in the Starlight integration or on a page-by-page basis in frontmatter.

By default, <h2> and <h3> headings are included in the table of contents. Change which headings levels to include site-wide using the minHeadingLevel and maxHeadingLevel options in your global tableOfContents. Override these defaults on an individual page by adding the corresponding frontmatter tableOfContents properties:

Disable the table of contents entirely by setting the tableOfContents option to false:

Social links

Starlight has built-in support for adding links to your social media accounts to the site header via the social option in the Starlight integration.

Each entry in the social array must be an object with three properties:

• icon: one of Starlight’s built-in icons, e.g. "github".
• label: an accessible label for the link, e.g. "GitHub".
• href: the URL for the link, e.g. "https://github.com/withastro/starlight".

The following example adds links to the Astro Discord chat and the Starlight GitHub repository:

astro.config.mjs

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'Docs With Social Links',
      social: [
        { icon: 'discord', label: 'Discord', href: 'https://astro.build/chat' },
        {
          icon: 'github',
          label: 'GitHub',
          href: 'https://github.com/withastro/starlight',
        },
      ],
    }),
  ],
});

Edit links

Starlight can display an “Edit page” link in each page’s footer. This makes it easy for a reader to find the file to edit to improve your docs. For open-source projects in particular, this can help encourage contributions from your community.

To enable edit links, set editLink.baseUrl to the URL used to edit your repository in the Starlight integration config. The value of editLink.baseUrl will be prepended to the path to the current page to form the full edit link.

Common patterns include:

• GitHub: https://github.com/USER_NAME/REPO_NAME/edit/BRANCH_NAME/
• GitLab: https://gitlab.com/USER_NAME/REPO_NAME/-/edit/BRANCH_NAME/

If your Starlight project is not in the root of your repository, include the path to the project at the end of the base URL.

This example shows the edit link configured for the Starlight docs, which live in the docs/ subdirectory on the main branch of the withastro/starlight repository on GitHub:

astro.config.mjs

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'Docs With Edit Links',
      editLink: {
        baseUrl: 'https://github.com/withastro/starlight/edit/main/docs/',
      },
    }),
  ],
});

Custom 404 page

Starlight sites display a simple 404 page by default. You can customize this by adding a 404.md (or 404.mdx) file to your src/content/docs/ directory:

You can use all of Starlight’s page layout and customization techniques in your 404 page. For example, the default 404 page uses the splash template and hero component in frontmatter:

src/content/docs/404.md

---
title: '404'
template: splash
editUrl: false
hero:
  title: '404'
  tagline: Page not found. Check the URL or try using the search bar.
---

Disabling the default 404 page

If your project requires an entirely customized 404 layout, you can create a src/pages/404.astro route and set the disable404Route config option to disable Starlight’s default route:

astro.config.mjs

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'Docs With Custom 404',
      disable404Route: true,
    }),
  ],
});

Custom fonts

By default, Starlight uses sans-serif fonts available on a user’s local device for all text. This ensures documentation loads quickly in a font that is familiar to each user, without requiring extra bandwidth to download large font files.

If you must add a custom font to your Starlight site, you can set up fonts to use in custom CSS files or with any other Astro styling technique.

Set up fonts

If you already have font files, follow the local set-up guide. To use Google Fonts, follow the Fontsource set-up guide.

Set up local font files

Set up a Fontsource font

The Fontsource project simplifies using Google Fonts and other open-source fonts. It provides npm modules you can install for the fonts you want to use and includes ready-made CSS files to add to your project.

Use fonts

To apply the font you set up to your site, use your chosen font’s name in a custom CSS file. For example, to override Starlight’s default font everywhere, set the --sl-font custom property:

src/styles/custom.css

:root {
  --sl-font: 'IBM Plex Serif', serif;
}

You can also write more targeted CSS if you want to apply your font more selectively. For example, to only set a font on the main content, but not the sidebars:

src/styles/custom.css

main {
  font-family: 'IBM Plex Serif', serif;
}

Follow the custom CSS instructions to add your styles to your site.