Custom Theme trong Astro Starlight

Custom Theme trong Astro Starlight

Giới thiệu

Astro Starlight cung cấp nhiều cách để tùy chỉnh giao diện mà không cần fork theme. Bạn có thể thay đổi màu sắc, typography, layout và thêm components tùy chỉnh.

Cấu hình cơ bản

Thêm custom CSS

astro.config.mjs

import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      customCss: [
        // Path to your custom CSS
        './src/styles/custom.css',
      ],
    }),
  ],
});

Tùy chỉnh màu sắc

Dark/Light Mode Colors

src/styles/custom.css

:root {
  /* Brand colors */
  --sl-hue-accent: 220; /* Thay đổi màu accent (0-360) */
  --sl-hue-gray: 250;    /* Thay đổi màu gray */

  /* Light mode */
  --sl-color-accent-low: #e8f0ff;
  --sl-color-accent: #3b82f6;
  --sl-color-accent-high: #dbeafe;

  /* Text colors */
  --sl-color-white: #1e293b;
  --sl-color-gray-1: #334155;
  --sl-color-gray-2: #475569;
  --sl-color-gray-3: #64748b;
  --sl-color-gray-4: #94a3b8;
  --sl-color-gray-5: #cbd5e1;
  --sl-color-gray-6: #f1f5f9;
  --sl-color-black: #f8fafc;
}

/* Dark mode */
:root[data-theme='dark'] {
  --sl-color-accent-low: #1e3a5f;
  --sl-color-accent: #60a5fa;
  --sl-color-accent-high: #dbeafe;

  --sl-color-white: #f8fafc;
  --sl-color-gray-1: #e2e8f0;
  --sl-color-gray-2: #cbd5e1;
  --sl-color-gray-3: #94a3b8;
  --sl-color-gray-4: #64748b;
  --sl-color-gray-5: #475569;
  --sl-color-gray-6: #1e293b;
  --sl-color-black: #0f172a;
}

Tùy chỉnh Typography

src/styles/custom.css

:root {
  --sl-font-system: 'Inter', system-ui, sans-serif;
  --sl-font-mono: 'JetBrains Mono', 'Fira Code', monospace;
}

/* Thay đổi font sizes */
:root {
  --sl-text-xs: 0.75rem;
  --sl-text-sm: 0.875rem;
  --sl-text-base: 1rem;
  --sl-text-lg: 1.125rem;
  --sl-text-xl: 1.25rem;
  --sl-text-2xl: 1.5rem;
  --sl-text-3xl: 1.875rem;
  --sl-text-4xl: 2.25rem;
}

/* Thêm Google Fonts */
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap');

Tùy chỉnh Components

Custom Head

src/components/CustomHead.astro

<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<meta name="theme-color" content="#3b82f6" />

astro.config.mjs

import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      head: [
        {
          tag: 'link',
          attrs: {
            rel: 'stylesheet',
            href: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap',
          },
        },
      ],
    }),
  ],
});

Custom Header

src/components/CustomHeader.astro

<header class="custom-header">
  <a href="/" class="logo">
    <img src="/logo.svg" alt="Logo" />
    <span>My Docs</span>
  </a>
  <nav>
    <a href="/docs">Docs</a>
    <a href="/blog">Blog</a>
    <a href="https://github.com/username/repo">GitHub</a>
  </nav>
</header>

<style>
  .custom-header {
    display: flex;
    align-items: center;
    justify-content: space-between;
    padding: 1rem 2rem;
    border-bottom: 1px solid var(--sl-color-gray-5);
  }

  .logo {
    display: flex;
    align-items: center;
    gap: 0.5rem;
    font-weight: 600;
    text-decoration: none;
  }

  nav {
    display: flex;
    gap: 1.5rem;
  }
</style>

Tùy chỉnh Sidebar

astro.config.mjs

import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      sidebar: [
        {
          label: 'Getting Started',
          items: [
            { label: 'Introduction', link: '/guides/intro/' },
            { label: 'Installation', link: '/guides/installation/' },
          ],
        },
        {
          label: 'API Reference',
          autogenerate: { directory: 'api' },
        },
        {
          label: 'External Links',
          link: 'https://external-site.com',
        },
      ],
    }),
  ],
});

Tùy chỉnh Social Links

astro.config.mjs

import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      social: {
        github: 'https://github.com/username/repo',
        discord: 'https://discord.gg/invite-code',
        twitter: 'https://twitter.com/username',
      },
    }),
  ],
});

Tùy chỉnh Table of Contents

astro.config.mjs

import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      toc: {
        minHeadingLevel: 2,
        maxHeadingLevel: 4,
      },
    }),
  ],
});

Tùy chỉnh components mặc định

Overriding Components

astro.config.mjs

import starlight from '@astrojs/starlight';
import starlightThemeFromCss from '@astrojs/starlight/themes/starlight.css.js';
import { defineConfig } from 'astro/config';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      components: {
        // Override default components
        ThemeSelect: './src/components/CustomThemeSelect.astro',
        Sidebar: './src/components/CustomSidebar.astro',
      },
    }),
  ],
});

Ví dụ: Glassmorphism Theme

src/styles/glass.css

/* Header với glass effect */
.site-title {
  background: rgba(255, 255, 255, 0.1);
  backdrop-filter: blur(10px);
  border-radius: 8px;
  padding: 0.5rem 1rem;
}

/* Sidebar với glass effect */
.sidebar-content {
  background: rgba(255, 255, 255, 0.05);
  backdrop-filter: blur(10px);
}

/* Content area */
.content-panel {
  background: rgba(255, 255, 255, 0.8);
  backdrop-filter: blur(20px);
  border-radius: 16px;
  margin: 1rem;
  padding: 2rem;
  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.1);
}

/* Dark mode adjustments */
:root[data-theme='dark'] .content-panel {
  background: rgba(15, 23, 42, 0.8);
}

Best Practices

1. Dùng CSS custom thay vì fork theme - Dễ maintain hơn

2. Tạo file CSS riêng - src/styles/custom.css cho mỗi theme variant

3. Sử dụng CSS variables - Starlight cung cấp sẵn nhiều variables

4. Test cả light và dark mode - Đảm bảo consistent experience

5. Override components cần thiết - Không override quá nhiều

Kết luận

Starlight cung cấp đủ flexibility để tạo docs site đẹp mà không cần fork:

• ✅ CSS Variables - Tùy chỉnh màu dễ dàng
• ✅ Custom Components - Thay đổi any part của UI
• ✅ customCss - Import any CSS
• ✅ head config - Thêm meta tags, fonts
• ✅ Social links - Built-in social integrations

Hãy tận dụng các tính năng có sẵn trước khi nghĩ đến việc fork!