跳转到内容

CSS 和样式

你可以使用自定义 CSS 文件或 Starlight Tailwind 插件来为你的 Starlight 站点设置样式。

要快速更改站点的默认样式,请查看社区主题

通过提供额外的 CSS 文件来修改或扩展 Starlight 的默认样式,从而自定义应用于你的 Starlight 站点的样式。

  1. 在你的 src/ 目录下添加一个 CSS 文件。例如,你可以为页面标题设置更宽的默认列宽和更大的文本大小

    src/styles/custom.css
    :root {
    --sl-content-width: 50rem;
    --sl-text-5xl: 3.5rem;
    }
  2. 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 层的样式的优先级顺序

src/styles/custom.css
@layer my-reset, starlight, my-overrides;

上面的示例定义了一个名为 my-reset 的自定义层,它在所有 Starlight 层之前应用;另一个名为 my-overrides 的层,它在所有 Starlight 层之后应用。 my-overrides 层中的任何样式都将优先于 Starlight 的样式,但 Starlight 仍然可以更改 my-reset 层中设置的样式。

Astro 项目中的 Tailwind CSS 支持由 Tailwind Vite 插件提供。Starlight 提供了补充的 CSS 来帮助配置 Tailwind 以与 Starlight 的样式兼容。

Starlight Tailwind CSS 应用以下配置

  • 配置 Tailwind 的 dark: 变体以与 Starlight 的暗黑模式配合使用。
  • 在 Starlight 的 UI 中使用 Tailwind 的主题颜色和字体
  • 恢复 Tailwind 的 Preflight 重置样式的基本部分。

使用 create astro 启动一个预先配置了 Tailwind CSS 的新 Starlight 项目

终端窗口
npm create astro@latest -- --template starlight/tailwind

如果你已经有一个 Starlight 站点并希望添加 Tailwind CSS,请按照以下步骤操作。

  1. 通过运行以下命令并在终端中按照说明操作,在你的项目中设置 Tailwind

    终端窗口
    npx astro add tailwind
  2. 安装 Starlight 的 Tailwind 兼容性包

    终端窗口
    npm install @astrojs/starlight-tailwind
  3. 替换由 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);
  4. 更新 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()] },
    });

Starlight 将在其 UI 中使用来自你的 Tailwind 主题配置 的值。

如果设置,以下 CSS 自定义属性将覆盖 Starlight 的默认样式

  • --color-accent-* — 用于链接和当前项目高亮
  • --color-gray-* — 用于背景颜色和边框
  • --font-sans — 用于 UI 和内容文本
  • --font-mono — 用于代码示例
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);
@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 文件中,以将此主题应用于你的网站。