跳转到内容

CSS & 样式

你可以使用自定义 CSS 设置你的 Starlight 网站的样式或者使用 Starlight Tailwind 插件。

有一种快速的方法可以更改你的网站的默认样式,请查看 社区主题

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

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

    src/styles/custom.css
    :root {
    --sl-content-width: 50rem;
    --sl-text-5xl: 3.5rem;
    }
  2. astro.config.mjs 中的 customCss 数组中添加你的 CSS 文件的路径:

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import starlight from '@astrojs/starlight';
    export default defineConfig({
    integrations: [
    starlight({
    title: 'Docs With Custom CSS',
    customCss: [
    // 你的自定义 CSS 文件的相对路径
    './src/styles/custom.css',
    ],
    }),
    ],
    });

你可以在 GitHub 上的 props.css 文件 中查看 Starlight 使用的所有 CSS 自定义属性,你可以设置这些属性来自定义你的网站。

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

Starlight Tailwind 插件应用了以下配置:

  • 配置 Tailwind 的 dark: 变体以与 Starlight 的暗模式兼容。
  • 在 Starlight 的 UI 中使用 Tailwind 主题颜色和字体
  • 禁用 Tailwind 的 Preflight 重置样式,同时有选择地恢复 Preflight 的必要部分,以便使用 Tailwind 的边框实用程序类。

使用 create astro 创建一个预配置了 Tailwind CSS 的新 Starlight 项目:

Terminal window
npm create astro@latest -- --template starlight/tailwind

如果你已经有了一个 Starlight 网站,并且想要添加 Tailwind CSS,请按照以下步骤操作。

  1. 将 Astro 的 Tailwind 集成添加到项目中:

    Terminal window
    npx astro add tailwind
  2. 安装 Starlight Tailwind 插件:

    Terminal window
    npm install @astrojs/starlight-tailwind
  3. 创建一个 CSS 文件,用于 Tailwind 的基础样式,例如在 src/tailwind.css 中:

    src/tailwind.css
    @tailwind base;
    @tailwind components;
    @tailwind utilities;
  4. 更新你的 Astro 配置文件,使用你的 Tailwind 基础样式并禁用默认的基础样式:

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import starlight from '@astrojs/starlight';
    import tailwind from '@astrojs/tailwind';
    export default defineConfig({
    integrations: [
    starlight({
    title: 'Docs with Tailwind',
    customCss: [
    // 你的 Tailwind 基础样式的相对路径
    './src/tailwind.css',
    ],
    }),
    tailwind({
    // 禁用默认的基础样式
    applyBaseStyles: false,
    }),
    ],
    });
  5. 将 Starlight Tailwind 插件添加到 tailwind.config.mjs

    tailwind.config.mjs
    import starlightPlugin from '@astrojs/starlight-tailwind';
    /** @type {import('tailwindcss').Config} */
    export default {
    content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
    plugins: [starlightPlugin()],
    };

使用 Tailwind 设置 Starlight 的样式

Section titled “使用 Tailwind 设置 Starlight 的样式”

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

如果设置了以下选项,将覆盖 Starlight 的默认样式:

  • colors.accent — 用于链接和当前项目高亮
  • colors.gray — 用于背景颜色和边框
  • fontFamily.sans — 用于 UI 和内容文本
  • fontFamily.mono — 用于代码示例
tailwind.config.mjs
import starlightPlugin from '@astrojs/starlight-tailwind';
import colors from 'tailwindcss/colors';
/** @type {import('tailwindcss').Config} */
export default {
content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
theme: {
extend: {
colors: {
// 你喜欢的强调色。Indigo 是最接近 Starlight 默认的。
accent: colors.indigo,
// 你喜欢的灰色。Zinc 是最接近 Starlight 默认的。
gray: colors.zinc,
},
fontFamily: {
// 你喜欢的文本字体。Starlight 默认使用系统字体堆栈。
sans: ['"Atkinson Hyperlegible"'],
// 你喜欢的代码字体。Starlight 默认使用系统等宽字体。
mono: ['"IBM Plex Mono"'],
},
},
},
plugins: [starlightPlugin()],
};

Starlight 的颜色主题可以通过覆盖其默认的自定义属性来控制。 这些变量在整个 UI 中使用,使用一系列灰色阴影用于文本和背景颜色,以及用于链接和突出显示导航中当前项目的强调色。

使用下面的滑块来修改 Starlight 的强调色和灰色调色板。暗色和亮色的预览区域将显示结果颜色,整个页面也会更新以预览你的更改。

使用“对比度级别”选项来指定要满足的 Web 内容无障碍功能指南的颜色对比度标准

当你对你的更改满意时,复制下面的 CSS 或 Tailwind 代码并在你的项目中使用。

预设
对比度级别
强调色
灰色

深色模式

正文以灰色阴影显示,与背景形成高对比度。 链接是彩色的。 有些文本(如目录)具有较低的对比度。 内联代码具有独特的背景颜色。

浅色模式

正文以灰色阴影显示,与背景形成高对比度。 链接是彩色的。 有些文本(如目录)具有较低的对比度。 内联代码具有独特的背景颜色。

将以下 CSS 添加到你的项目的自定义 CSS 文件中,以将此主题应用到你的网站。