Starlight Plugin Icons - Thêm Icons vào Sidebar và Code Blocks

Tổng quan

starlight-plugin-icons là plugin mở rộng Starlight với 2 tính năng chính:

1. Sidebar Icons - Thêm icon vào các mục trong sidebar
2. Code Block Icons - Hiển thị Material Icons tự động cho code blocks dựa trên ngôn ngữ

⚠️ Lưu ý quan trọng: Plugin này KHÔNG hoạt động với dự án có Svelte components. Khi cài đặt, sẽ gặp lỗi:

Failed to parse source for import analysis because the content contains invalid JS syntax

Nguyên nhân: Plugin cố gắng parse các file .svelte nhưng chúng không phải JS/JSX hợp lệ.

Tính năng chính

1. Sidebar Icons

Thêm icon vào các mục trong sidebar config:

starlight.config.mjs

import starlightPluginIcons from 'starlight-plugin-icons';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      plugins: [
        starlightPluginIcons(),
      ],
      sidebar: [
        {
          label: 'Getting Started',
          icon: 'i-ph:hand-waving-duotone',  // ✅ Icon ở đây
          items: [
            { label: 'Introduction', link: '/intro' },
            { label: 'Installation', icon: 'i-ph:package-duotone', link:          ],
        },
      ],
    }),
 '/install' },
  ],
});

2. Code Block Icons

Tự động hiển thị icon dựa trên ngôn ngữ hoặc title:

```javascript
// Tự động hiển thị JavaScript icon
function hello() {
  console.log('Hello');
}
```

```python title="main.py"
# Tự động hiển thị Python icon
def hello():
    print("Hello")
```

3. Improved Components

Plugin còn cải tiến các components có sẵn:

FileTree Component

<FileTree>
  <FileTree.Folder name="src" />
  <FileTree.File name="index.ts" />
  <FileTree.Folder name="components">
    <FileTree.File name="Button.tsx" />
  </FileTree.Folder>
</FileTree>

Tự động hiển thị folder/file icons dựa trên tên.

Card Component

import { Card } from '@astrojs/starlight/components';

<Card icon="i-ph:rocket-duotone">
  Thêm icon vào card
</Card>

Aside Component

import { Aside } from '@astrojs/starlight/components';

<Aside type="tip" icon="i-ph:lightbulb-duotone">
  Mẹo hữu ích!
</Aside>

IconLink Component

import { IconLink } from '@astrojs/starlight-components';

<IconLink
  icon="i-ph:github-logo"
  href="https://github.com"
  label="GitHub"
/>

Cài đặt

npm install starlight-plugin-icons

Cấu hình trong astro.config.mjs:

import starlightPluginIcons from 'starlight-plugin-icons';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      plugins: [
        starlightPluginIcons(),
      ],
    }),
  ],
});

Icon Sets được hỗ trợ

Plugin sử dụng Iconify nên hỗ trợ hàng ngàn icon sets:

• i-ph: - Phosphor Icons
• i-heroicons: - Heroicons
• i-mdi: - Material Design Icons
• i-logos: - Logo icons
• i-devicon: - Devicon

Cách sử dụng icon:

// Phosphor Icons
icon: 'i-ph:hand-waving-duotone'

// GitHub logo
icon: 'i-ph:github-logo-duotone'

// Code languages
icon: 'i-ph:code-block-duotone'

Cấu hình nâng cao

Custom Icon Mapping

starlightPluginIcons({
  // Map code block title sang icon
  codeblockIconMap: {
    'main.py': 'i-ph:file-python-duotone',
    'app.js': 'i-ph:file-js-duotone',
  },
}),

Safelist Icons

Đảm bảo icons được include trong build:

starlightPluginIcons({
  // Force include icons
  iconMetaMap: {
    'i-ph:rocket-duotone': {
      icon: 'i-ph:rocket-duotone',
    },
  },
}),

So sánh

Tính năng	Không dùng plugin	starlight-plugin-icons
Sidebar icons	Thủ công, tự code	✅ Tự động
Code block icons	❌ Không có	✅ Tự động
FileTree icons	Cần tự thêm	✅ Tự động
Performance	-	Build-time only

Khi nào nên dùng?

• ✅ Docs cần sidebar đẹp hơn với icons
• ✅ Muốn code blocks có icon theo ngôn ngữ
• ✅ Cần FileTree component với icons tự động
• ✅ Muốn dùng IconLink, Aside với icons

Kết luận

starlight-plugin-icons là plugin nhẹ, build-time only, giúp:

• Tăng UX với sidebar icons
• Code blocks trực quan hơn
• Cải tiến các components có sẽn

Tham khảo

• starlight-plugin-icons
• GitHub
• Iconify