CSS 和样式
你可以使用自定义 CSS 文件或 Starlight Tailwind 插件来为你的 Starlight 站点设置样式。
要快速更改站点的默认样式,请查看社区主题。
自定义 CSS 样式
标题为“自定义 CSS 样式”的部分通过提供额外的 CSS 文件来修改或扩展 Starlight 的默认样式,从而自定义应用于你的 Starlight 站点的样式。
-
在你的
src/
目录下添加一个 CSS 文件。例如,你可以为页面标题设置更宽的默认列宽和更大的文本大小src/styles/custom.css :root {--sl-content-width: 50rem;--sl-text-5xl: 3.5rem;} -
在
astro.config.mjs
中,将你的 CSS 文件路径添加到 Starlight 的customCss
数组中astro.config.mjs import { defineConfig } from 'astro/config';import starlight from '@astrojs/starlight';export default defineConfig({integrations: [starlight({title: 'Docs With Custom CSS',customCss: [// Relative path to your custom CSS file'./src/styles/custom.css',],}),],});
你可以在 GitHub 上的 props.css
文件中查看 Starlight 使用的所有 CSS 自定义属性,你可以设置这些属性来自定义你的网站。
层叠层
标题为“层叠层”的部分Starlight 在内部使用层叠层来管理其样式的顺序。这确保了可预测的 CSS 顺序,并允许更简单的覆盖。任何自定义的未分层的 CSS 都将覆盖默认的 Starlight 样式。
如果你正在使用层叠层,你可以在自定义 CSS 中使用 @layer
来定义不同层相对于 starlight
层的样式的优先级顺序
@layer my-reset, starlight, my-overrides;
上面的示例定义了一个名为 my-reset
的自定义层,它在所有 Starlight 层之前应用;另一个名为 my-overrides
的层,它在所有 Starlight 层之后应用。 my-overrides
层中的任何样式都将优先于 Starlight 的样式,但 Starlight 仍然可以更改 my-reset
层中设置的样式。
Tailwind CSS
标题为“Tailwind CSS”的部分Astro 项目中的 Tailwind CSS 支持由 Tailwind Vite 插件提供。Starlight 提供了补充的 CSS 来帮助配置 Tailwind 以与 Starlight 的样式兼容。
Starlight Tailwind CSS 应用以下配置
- 配置 Tailwind 的
dark:
变体以与 Starlight 的暗黑模式配合使用。 - 在 Starlight 的 UI 中使用 Tailwind 的主题颜色和字体。
- 恢复 Tailwind 的 Preflight 重置样式的基本部分。
使用 Tailwind 创建新项目
标题为“使用 Tailwind 创建新项目”的部分使用 create astro
启动一个预先配置了 Tailwind CSS 的新 Starlight 项目
npm create astro@latest -- --template starlight/tailwind
pnpm create astro --template starlight/tailwind
yarn create astro --template starlight/tailwind
将 Tailwind 添加到现有项目
标题为“将 Tailwind 添加到现有项目”的部分如果你已经有一个 Starlight 站点并希望添加 Tailwind CSS,请按照以下步骤操作。
-
通过运行以下命令并在终端中按照说明操作,在你的项目中设置 Tailwind
终端窗口 npx astro add tailwind终端窗口 pnpm astro add tailwind终端窗口 yarn astro add tailwind -
安装 Starlight 的 Tailwind 兼容性包
终端窗口 npm install @astrojs/starlight-tailwind终端窗口 pnpm add @astrojs/starlight-tailwind终端窗口 yarn add @astrojs/starlight-tailwind -
替换由 Astro 为与 Starlight 兼容而生成的
src/styles/global.css
文件的内容src/styles/global.css @layer base, starlight, theme, components, utilities;@import '@astrojs/starlight-tailwind';@import 'tailwindcss/theme.css' layer(theme);@import 'tailwindcss/utilities.css' layer(utilities); -
更新 Starlight 配置,将 Tailwind CSS 文件添加为
customCss
数组中的第一项astro.config.mjs import { defineConfig } from 'astro/config';import starlight from '@astrojs/starlight';import tailwindcss from '@tailwindcss/vite';export default defineConfig({integrations: [starlight({title: 'Docs with Tailwind',customCss: [// Path to your Tailwind base styles:'./src/styles/global.css',],}),],vite: { plugins: [tailwindcss()] },});
使用 Tailwind 设计 Starlight 样式
标题为“使用 Tailwind 设计 Starlight 样式”的部分Starlight 将在其 UI 中使用来自你的 Tailwind 主题配置 的值。
如果设置,以下 CSS 自定义属性将覆盖 Starlight 的默认样式
--color-accent-*
— 用于链接和当前项目高亮--color-gray-*
— 用于背景颜色和边框--font-sans
— 用于 UI 和内容文本--font-mono
— 用于代码示例
@layer base, starlight, theme, components, utilities;
@import '@astrojs/starlight-tailwind';@import 'tailwindcss/theme.css' layer(theme);@import 'tailwindcss/utilities.css' layer(utilities);
@theme { /* Your preferred text font. Starlight uses a system font stack by default. */ --font-sans: 'Atkinson Hyperlegible'; /* Your preferred code font. Starlight uses system monospace fonts by default. */ --font-mono: 'IBM Plex Mono'; /* Your preferred accent color. Indigo is closest to Starlight’s defaults. */ --color-accent-50: var(--color-indigo-50); --color-accent-100: var(--color-indigo-100); --color-accent-200: var(--color-indigo-200); --color-accent-300: var(--color-indigo-300); --color-accent-400: var(--color-indigo-400); --color-accent-500: var(--color-indigo-500); --color-accent-600: var(--color-indigo-600); --color-accent-700: var(--color-indigo-700); --color-accent-800: var(--color-indigo-800); --color-accent-900: var(--color-indigo-900); --color-accent-950: var(--color-indigo-950); /* Your preferred gray scale. Zinc is closest to Starlight’s defaults. */ --color-gray-50: var(--color-zinc-50); --color-gray-100: var(--color-zinc-100); --color-gray-200: var(--color-zinc-200); --color-gray-300: var(--color-zinc-300); --color-gray-400: var(--color-zinc-400); --color-gray-500: var(--color-zinc-500); --color-gray-600: var(--color-zinc-600); --color-gray-700: var(--color-zinc-700); --color-gray-800: var(--color-zinc-800); --color-gray-900: var(--color-zinc-900); --color-gray-950: var(--color-zinc-950);}
主题化
标题为“主题化”的部分Starlight 的颜色主题可以通过覆盖其默认的自定义属性来控制。这些变量在整个 UI 中使用,其中一系列灰色调用于文本和背景颜色,而强调色用于链接和高亮导航中的当前项目。
颜色主题编辑器
标题为“颜色主题编辑器”的部分使用下面的滑块修改 Starlight 的强调色和灰色调色板。暗色和亮色预览区域将显示生成的颜色,整个页面也会更新以预览你的更改。
使用“对比度级别”选项来指定要满足的网页内容无障碍指南(WCAG)颜色对比度标准。
当你对更改满意后,复制下面的 CSS 或 Tailwind 代码并在你的项目中使用。
暗黑模式
正文文本以高对比度的灰色调显示在背景上。 链接是彩色的。 一些文本,如目录,对比度较低。 内联代码有独特的背景。
亮色模式
正文文本以高对比度的灰色调显示在背景上。 链接是彩色的。 一些文本,如目录,对比度较低。 内联代码有独特的背景。
将以下 CSS 添加到你的项目的自定义 CSS 文件中,以将此主题应用于你的网站。
将以下 CSS 变量添加到你的 Tailwind CSS 文件中的 @theme
块中,以将此主题应用于你的网站。