自定义 Starlight
Starlight 提供了合理的默认样式和功能,因此你无需配置即可快速上手。当你想开始自定义 Starlight 站点的外观和体验时,本指南将为你提供帮助。
添加你的 Logo
标题为“添加你的 Logo”的部分将自定义 Logo 添加到网站标题是为 Starlight 网站添加个人品牌的快捷方式。
-
将你的 Logo 图片文件添加到
src/assets/
目录中目录src/
目录assets/
- my-logo.svg
目录content/
- …
- astro.config.mjs
-
在
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: '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 变体”的部分你可以在浅色和深色模式下显示不同版本的 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 Pagetemplate: splash---
Starlight 在每个页面上都显示一个目录,使读者更容易跳转到他们正在寻找的标题。你可以在 Starlight 集成中全局自定义甚至禁用目录,或者在 frontmatter 中逐页进行设置。
默认情况下,<h2>
和 <h3>
标题会包含在目录中。通过在你的全局 tableOfContents
配置中使用 minHeadingLevel
和 maxHeadingLevel
选项,可以更改全站包含的标题级别。通过添加相应的 frontmatter tableOfContents
属性,可以在单个页面上覆盖这些默认值
---title: Page with only H2s in the table of contentstableOfContents: minHeadingLevel: 2 maxHeadingLevel: 2---
defineConfig({ integrations: [ starlight({ title: 'Docs with custom table of contents config', tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 2 }, }), ],});
通过将 tableOfContents
选项设置为 false
来完全禁用目录
---title: Page without a table of contentstableOfContents: 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 页面
标题为“自定义 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: splasheditUrl: falsehero: title: '404' tagline: Page not found. Check the URL or try using the search bar.---
禁用默认 404 页面
标题为“禁用默认 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()
函数中使用字体文件的相对路径。src/fonts/font-face.css @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
数组中astro.config.mjs 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 字体”的部分Fontsource 项目简化了 Google Fonts 和其他开源字体的使用。它为你想要使用的字体提供了可以安装的 npm 模块,并包含了可添加到项目中的现成 CSS 文件。
-
在 Fontsource 的目录中找到你想要使用的字体。本例将使用 IBM Plex Serif。
-
为你选择的字体安装相应的包。你可以在 Fontsource 字体页面上点击“Install”来找到包名。
终端窗口 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
数组中astro.config.mjs 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 说明将你的样式添加到你的网站。