跳转到内容

自定义 Starlight

Starlight 提供了合理的默认样式和功能,因此你可以快速开始,无需配置即可进行操作。 当你想要开始自定义 Starlight 网站的外观时,本指南可以帮助你。

将自定义 logo 添加到网站标题是将品牌形象添加到 Starlight 网站的快速方法。

  1. 将你的 logo 图像文件添加到 src/assets/ 目录:

    • Directorysrc/
      • Directoryassets/
        • my-logo.svg
      • Directorycontent/
    • astro.config.mjs
  2. astro.config.mjs 中,将 logo 的路径添加到 Starlight 的 logo.src 选项:

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import starlight from '@astrojs/starlight';
    export default defineConfig({
    integrations: [
    starlight({
    title: '带有我的标志的页面',
    logo: {
    src: './src/assets/my-logo.svg',
    },
    }),
    ],
    });

默认情况下,logo 将显示在网站的标题旁边。 如果你的 logo 图像已经包含了网站标题,你可以通过设置 replacesTitle 选项来在视觉上隐藏标题文本。 标题文本仍包含在屏幕阅读器中,以便标题保持可访问性。

starlight({
title: '带有我的 logo 的页面',
logo: {
src: './src/assets/my-logo.svg',
replacesTitle: true,
},
}),

亮色和暗色 logo 变体

你可以在亮色和暗色模式下显示不同版本的 logo。

  1. 将每个变体的图像文件添加到 src/assets/

    • Directorysrc/
      • Directoryassets/
        • light-logo.svg
        • dark-logo.svg
      • Directorycontent/
    • astro.config.mjs
  2. astro.config.mjs 中,将 logo 变体的路径添加为 lightdark 选项,而不是 src

    starlight({
    title: '带有我的标志的页面',
    logo: {
    light: './src/assets/light-logo.svg',
    dark: './src/assets/dark-logo.svg',
    },
    }),

启用 sitemap

Starlight 内置了生成站点地图(sitemap)的支持。通过在 astro.config.mjs 中把 site 字段设置为你的 URL 来启用站点地图生成:

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

页面布局

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

你可以通过在页面的正文中设置 template: splash 来应用更宽的页面布局,而去除侧边栏。 这对于主页面特别有效,你可以在本站点的主页上看到它的效果。

src/content/docs/index.md
---
title: 我的主页面
template: splash
---

目录

Starlight 在每个页面上显示目录,使读者更容易跳转到他们正在寻找的标题。你可以在 Starlight 集成中全局自定义目录或在 frontmatter 中逐个页面进行设置。

默认情况下,目录中包含 <h2><h3> 标题。使用全局 tableOfContents 中的 minHeadingLevelmaxHeadingLevel 选项更改要包含的标题级别。通过添加相应的 frontmatter 中的 tableOfContents 属性,在单个页面上覆盖这些默认值:

src/content/docs/example.md
---
title: 只在目录中包含 H2 的页面
tableOfContents:
minHeadingLevel: 2
maxHeadingLevel: 2
---

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

src/content/docs/example.md
---
title: 没有目录的页面
tableOfContents: false
---

社交链接

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

你可以在 配置参考 中找到完整的支持链接图标列表。 如果你需要支持其他服务,请在 GitHub 或 Discord 上告诉我们!

astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
export default defineConfig({
integrations: [
starlight({
title: '带有社交链接的页面',
social: {
discord: 'https://astro.build/chat',
github: '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/ 子目录中:

astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
export default defineConfig({
integrations: [
starlight({
title: '带有编辑链接的页面',
editLink: {
baseUrl: 'https://github.com/withastro/starlight/edit/main/docs/',
},
}),
],
});

自定义 404 页面

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

  • Directorysrc/
    • Directorycontent/
      • Directorydocs/
        • 404.md
        • index.md
  • astro.config.mjs

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

src/content/docs/404.md
---
title: '404'
template: splash
editUrl: false
hero:
title: '404'
tagline: 页面未找到。请检查URL或尝试使用搜索栏。
---

自定义字体

默认情况下,Starlight 使用用户本地设备上可用的无衬线字体来显示所有文本。这样可以确保文档在加载时以每个用户熟悉的字体快速显示,而不需要额外的带宽下载大型字体文件。

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

设置字体

如果你已经拥有字体文件,请按照本地设置指南进行操作。如果要使用 Google Fonts,请按照 Fontsource 设置指南进行操作。

设置本地字体文件

  1. 将字体文件添加到 src/fonts/ 目录中,并创建一个空的 font-face.css 文件:

    • Directorysrc/
      • Directorycontent/
      • Directoryfonts/
        • CustomFont.woff2
        • font-face.css
    • astro.config.mjs
  2. src/fonts/font-face.css 中为每个字体添加一个 @font-face 声明。在 url() 函数中使用相对路径来引用字体文件:

    src/fonts/font-face.css
    @font-face {
    font-family: 'Custom Font';
    /* 使用相对路径来引用本地字体文件。 */
    src: url('./CustomFont.woff2') format('woff2');
    font-weight: normal;
    font-style: normal;
    font-display: swap;
    }
  3. font-face.css 文件的路径添加到 Starlight 的 astro.config.mjs 配置文件中的 customCss 数组中:

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import starlight from '@astrojs/starlight';
    export default defineConfig({
    integrations: [
    starlight({
    title: '使用自定义字体的页面',
    customCss: [
    // @font-face CSS文件的相对路径。
    './src/fonts/font-face.css',
    ],
    }),
    ],
    });

设置 Fontsource 字体

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

  1. Fontsource 目录中找到你想要使用的字体。本示例将使用 IBM Plex Serif 字体。

  2. 安装所选字体的包。你可以通过在 Fontsource 字体页面上点击 “Install” 按钮来找到包名称。

    Terminal window
    npm install @fontsource/ibm-plex-serif
  3. 将 Fontsource 的 CSS 文件添加到 Starlight 的 astro.config.mjs 配置文件中的 customCss 数组中:

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import starlight from '@astrojs/starlight';
    export default defineConfig({
    integrations: [
    starlight({
    title: '使用自定义字体的文档',
    customCss: [
    // 用于普通和半粗字重的 Fontsource 文件。
    '@fontsource/ibm-plex-serif/400.css',
    '@fontsource/ibm-plex-serif/600.css',
    ],
    }),
    ],
    });

    Fontsource 为每个字体提供了多个 CSS 文件。请参阅 Fontsource 文档以了解如何包含不同的字重和样式。

使用字体

要将设置好的字体应用于你的站点,请在自定义 CSS 文件中使用所选字体的名称。例如,要在整个站点上覆盖 Starlight 的默认字体,请设置--sl-font自定义属性:

src/styles/custom.css
:root {
--sl-font: 'IBM Plex Serif', serif;
}

如果你只想在主要内容上设置字体,而不在侧边栏上设置字体,请使用更具针对性的 CSS:

src/styles/custom.css
main {
font-family: 'IBM Plex Serif', serif;
}

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