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.
-
Add your logo image file to the
src/assets/
directory:Directorysrc/
Directoryassets/
- my-logo.svg
Directorycontent/
- …
- astro.config.mjs
-
Add the path to your logo as Starlight’s
logo.src
option inastro.config.mjs
:
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.
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
src/assets/
:Directorysrc/
Directoryassets/
- light-logo.svg
- dark-logo.svg
Directorycontent/
- …
- astro.config.mjs
-
Add the path to your logo variants as the
light
anddark
options instead ofsrc
inastro.config.mjs
:
Enable sitemap
Starlight has built-in support for generating a sitemap. Enable sitemap generation by setting your URL as site
in astro.config.mjs
:
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.
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.
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!
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:
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:
Directorysrc/
Directorycontent/
Directorydocs/
- 404.md
- index.md
- astro.config.mjs
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:
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:
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
-
Add your font files to a
src/fonts/
directory and create an emptyfont-face.css
file:Directorysrc/
Directorycontent/
- …
Directoryfonts/
- CustomFont.woff2
- font-face.css
- astro.config.mjs
-
Add an
@font-face
declaration for each of your fonts insrc/fonts/font-face.css
. Use a relative path to the font file in theurl()
function. -
Add the path to your
font-face.css
file to Starlight’scustomCss
array inastro.config.mjs
:
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.
-
Find the font you want to use in Fontsource’s catalog. This example will use IBM Plex Serif.
-
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
customCss
array inastro.config.mjs
:Fontsource ships multiple CSS files for each font. See the Fontsource documentation on including different weights and styles to understand which to use.
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:
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.