Starlight 主题使用笔记

Astro Starlight 主题使用笔记，这篇文章记录了配置 react、tailwindcss等的详细的调试过程。

添加 React 支持

给 Starlight 主题添加 react 支持，并提供 TypeScript 支持(.tsx):

安装依赖：

pnpm add @astrojs/react react react-dom

安装类型：

pnpm add -D @types/react @types/react-dom

注册 React

import react from '@astrojs/react'; // 引入 React 集成

export default defineConfig({
    integrations: [
        starlight({
            ...
        }),
        react(), // 注册 React 集成
    ],
    ...
});

添加 tailwindcss

Starlight 不支持 tailwindcss v4 版本，所以只能安装 v3

pnpm add -D tailwindcss@3 postcss autoprefixer

初始化配置：

pnpm npx tailwindcss init -p

配置 tailwind.config.js:

/** @type {import('tailwindcss').Config} */
export default {
  content: [
    "./src/**/*.{astro,html,js,jsx,ts,tsx,md,mdx}",
    "./node_modules/@astrojs/starlight/**/*.{astro,md,mdx}"
  ],
  theme: {
    extend: {},
  },
  corePlugins: {
    preflight: false, // 关键 关闭 Preflight, 保留 Tailwind，但禁用 reset，要不然会影响 Starlight 的默认样式
  },
  plugins: [],
}

global.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

postcss.config.js:

module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

astro.config.mjs:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import react from '@astrojs/react';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      customCss: ['./src/styles/global.css'],
    }),
    react(),
  ],
});

用 pnpm

在安装好 Starlight 后直接使用 pnpm install 即可，如果已经用 npm install 了，可以执行以下操作：

# 1️⃣ 删除 npm 产物
rm -rf node_modules package-lock.json

# 2️⃣ 用 pnpm 重新安装
pnpm install

添加数学公式

安装:

npm install @astrojs/mdx remark-math rehype-katex katex

其中 @astrojs/mdx 可以不安装，因为 Starlight 主题自带了。

配置：

astro.config.mjs

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import remarkMath from 'remark-math'; // 导入数学语法解析插件
import rehypeKatex from 'rehype-katex'; // 导入 KaTeX 渲染插件

export default defineConfig({
  integrations: [
    starlight({
      title: '我的文档',
      // ... 其他 Starlight 配置
    })
  ],
  markdown: {
    // 5. 配置 Markdown 处理器
    remarkPlugins: [remarkMath],
    rehypePlugins: [rehypeKatex],
  },
});

导入样式

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import mdx from '@astrojs/mdx';
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';

export default defineConfig({
  integrations: [
    starlight({
      title: '我的文档',
      head: [
        {
          tag: 'link',
          attrs: {
            rel: 'stylesheet',
            // 👇 使用 /node_modules/ 前缀，Astro 会自动解析
            href: '/node_modules/katex/dist/katex.min.css',
          },
        },
      ],
    }),
    mdx(),
  ],
  markdown: {
    remarkPlugins: [remarkMath],
    rehypePlugins: [rehypeKatex],
  },
});