自定义 Starlight

Starlight 提供了合理的默认样式和功能，因此你无需配置即可快速上手。当你想开始自定义 Starlight 站点的外观和体验时，本指南将为你提供帮助。

添加你的 Logo

将自定义 Logo 添加到网站标题是为 Starlight 网站添加个人品牌的快捷方式。

将你的 Logo 图片文件添加到 src/assets/ 目录中
- 目录src/
  - 目录assets/
    my-logo.svg
  - 目录content/
    …
- astro.config.mjs

在 astro.config.mjs 中，将你的 Logo 路径添加为 Starlight 的 logo.src 选项

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'Docs With My Logo',
      logo: {
        src: './src/assets/my-logo.svg',
      },
    }),
  ],
});

默认情况下，Logo 会与网站的 title 一同显示。如果你的 Logo 图片已经包含了网站标题，你可以通过设置 replacesTitle 选项来在视觉上隐藏标题文本。但 title 文本仍会为屏幕阅读器保留，以确保头部的可访问性。

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

浅色和深色 Logo 变体

你可以在浅色和深色模式下显示不同版本的 Logo。

将每种变体的图片文件添加到 src/assets/ 中
- 目录src/
  - 目录assets/
    light-logo.svg
    dark-logo.svg
  - 目录content/
    …
- astro.config.mjs

在 astro.config.mjs 中，将 Logo 变体的路径添加为 light 和 dark 选项，而不是 src。

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

启用站点地图

Starlight 内置了生成站点地图的支持。通过在 astro.config.mjs 中将你的 URL 设置为 site 来启用站点地图生成。

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

在 Astro 文档中了解如何将站点地图链接添加到 robots.txt。

页面布局

默认情况下，Starlight 页面使用带有全局导航侧边栏和显示当前页面标题的目录的布局。

你可以通过在页面的 frontmatter 中设置 template: splash 来应用更宽的、没有侧边栏的页面布局。这对于着陆页特别有效，你可以在本站的首页上看到它的实际效果。

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

默认情况下，<h2> 和 <h3> 标题会包含在目录中。通过在你的全局 tableOfContents 配置中使用 minHeadingLevel 和 maxHeadingLevel 选项，可以更改全站包含的标题级别。通过添加相应的 frontmatter tableOfContents 属性，可以在单个页面上覆盖这些默认值

Frontmatter
全局配置

---
title: Page with only H2s in the table of contents
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 2
---

defineConfig({
  integrations: [
    starlight({
      title: 'Docs with custom table of contents config',
      tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 2 },
    }),
  ],
});

通过将 tableOfContents 选项设置为 false 来完全禁用目录

Frontmatter
全局配置

---
title: Page without a table of contents
tableOfContents: false
---

defineConfig({
  integrations: [
    starlight({
      title: 'Docs with table of contents disabled globally',
      tableOfContents: false,
    }),
  ],
});

Starlight 内置了通过 Starlight 集成中的 social 选项向网站标题添加社交媒体帐户链接的支持。

social 数组中的每个条目都必须是具有三个属性的对象

icon：Starlight 的内置图标之一，例如 "github"。
label：链接的可访问性标签，例如 "GitHub"。
href：链接的 URL，例如 "https://github.com/withastro/starlight"。

以下示例添加了指向 Astro Discord 聊天和 Starlight GitHub 仓库的链接

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.js.cn/chat' },
        {
          icon: 'github',
          label: 'GitHub',
          href: 'https://github.com/withastro/starlight',
        },
      ],
    }),
  ],
});

编辑链接

Starlight 可以在每个页面的页脚显示一个“编辑此页”的链接。这使读者可以轻松找到要编辑的文件以改进你的文档。特别是对于开源项目，这有助于鼓励社区的贡献。

要启用编辑链接，请在 Starlight 集成配置中将 editLink.baseUrl 设置为用于编辑仓库的 URL。editLink.baseUrl 的值将被前置到当前页面的路径，以形成完整的编辑链接。

常见的模式包括

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

如果你的 Starlight 项目不在仓库的根目录中，请在基础 URL 的末尾包含项目的路径。

此示例显示了为 Starlight 文档配置的编辑链接，这些文档位于 GitHub 上 withastro/starlight 仓库的 main 分支下的 docs/ 子目录中

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/',
      },
    }),
  ],
});

自定义 404 页面

Starlight 网站默认显示一个简单的 404 页面。你可以通过在 src/content/docs/ 目录中添加一个 404.md（或 404.mdx）文件来自定义此页面

目录src/
- 目录content/
  - 目录docs/
    404.md
    index.md
astro.config.mjs

你可以在 404 页面中使用所有 Starlight 的页面布局和自定义技术。例如，默认的 404 页面在 frontmatter 中使用了 splash 模板和 hero 组件

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

禁用默认 404 页面

如果你的项目需要一个完全自定义的 404 布局，你可以创建一个 src/pages/404.astro 路由，并设置 disable404Route 配置选项来禁用 Starlight 的默认路由

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

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

自定义字体

默认情况下，Starlight 对所有文本使用用户本地设备上可用的无衬线字体。这确保了文档能够以每个用户熟悉的字体快速加载，而无需额外的带宽来下载大型字体文件。

如果你必须向你的 Starlight 网站添加自定义字体，你可以设置字体以在自定义 CSS 文件中使用，或使用任何其他 Astro 样式技术。

设置字体

如果你已经有字体文件，请遵循本地设置指南。要使用 Google Fonts，请遵循 Fontsource 设置指南。

设置本地字体文件

将你的字体文件添加到 src/fonts/ 目录，并创建一个空的 font-face.css 文件
- 目录src/
  - 目录content/
    …
  - 目录fonts/
    CustomFont.woff2
    font-face.css
- astro.config.mjs

在 src/fonts/font-face.css 中为你的每个字体添加一个 @font-face 声明。在 url() 函数中使用字体文件的相对路径。

@font-face {
  font-family: 'Custom Font';
  /* Use a relative path to the local font file in `url()`. */
  src: url('./CustomFont.woff2') format('woff2');
  font-weight: normal;
  font-style: normal;
  font-display: swap;
}

将你的 font-face.css 文件路径添加到 astro.config.mjs 中 Starlight 的 customCss 数组中

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'Docs With a Custom Typeface',
      customCss: [
        // Relative path to your @font-face CSS file.
        './src/fonts/font-face.css',
      ],
    }),
  ],
});

设置 Fontsource 字体

Fontsource 项目简化了 Google Fonts 和其他开源字体的使用。它为你想要使用的字体提供了可以安装的 npm 模块，并包含了可添加到项目中的现成 CSS 文件。

在 Fontsource 的目录中找到你想要使用的字体。本例将使用 IBM Plex Serif。
为你选择的字体安装相应的包。你可以在 Fontsource 字体页面上点击“Install”来找到包名。
- npm
- pnpm
- Yarn
终端窗口
npm install @fontsource/ibm-plex-serif
终端窗口
pnpm add @fontsource/ibm-plex-serif
终端窗口
yarn add @fontsource/ibm-plex-serif

将 Fontsource CSS 文件添加到 astro.config.mjs 中 Starlight 的 customCss 数组中

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'Docs With a Custom Typeface',
      customCss: [
        // Fontsource files for to regular and semi-bold font weights.
        '@fontsource/ibm-plex-serif/400.css',
        '@fontsource/ibm-plex-serif/600.css',
      ],
    }),
  ],
});

Fontsource 为每种字体提供了多个 CSS 文件。请参阅关于包含不同字重和样式的 Fontsource 文档，以了解使用哪个文件。

使用字体

要将你设置的字体应用到你的网站上，请在自定义 CSS 文件中使用你选择的字体名称。例如，要覆盖 Starlight 的默认字体，可以设置 --sl-font 自定义属性

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

如果你想更有选择性地应用你的字体，你也可以编写更具针对性的 CSS。例如，只在主内容区域设置字体，而不包括侧边栏

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

按照自定义 CSS 说明将你的样式添加到你的网站。