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.
Add your logo image file to the
Add the path to your logo as Starlight’s
By default, the logo will be displayed alongside your site’s
If your logo image already includes the site title, you can visually hide the title text by setting the
title text will still be included for screen readers so that the header remains accessible.
Light and dark logo variants
You can display different versions of your logo in light and dark modes.
Add an image file for each variant to
Add the path to your logo variants as the
darkoptions instead of
Starlight has built-in support for generating a sitemap. Enable sitemap generation by setting your URL as
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.
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.
<h3> headings are included in the table of contents. Change which headings levels to include site-wide using the
maxHeadingLevel options in your global
tableOfContents. Override these defaults on an individual page by adding the corresponding frontmatter
Disable the table of contents entirely by setting the
tableOfContents option to
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.
You can find a full list of supported link icons in the Configuration Reference. Let us know on GitHub or Discord if you need support for another service!
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:
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:
Custom 404 page
Starlight sites display a simple 404 page by default.
You can customize this by adding a
404.mdx) file to your
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
Set up local font files
Add your font files to a
src/fonts/directory and create an empty
@font-facedeclaration for each of your fonts in
src/fonts/font-face.css. Use a relative path to the font file in the
Add the path to your
font-face.cssfile to Starlight’s
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.
Install the package for your chosen font. You can find the package name by clicking “Install” on the Fontsource font page.
Add Fontsource CSS files to Starlight’s
Fontsource ships multiple CSS files for each font. See the Fontsource documentation on including different weights and styles to understand which to use.
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:
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:
Follow the custom CSS instructions to add your styles to your site.