메뉴
Starlight - Full-featured documentation theme built on Astro for creating beautiful, accessible, high-performance documentation websites with built-in search, i18n, and customizable components
기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.
설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.
npx skills add https://github.com/enuno/claude-command-and-control --skill starlight명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.
로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.
SKILL.md 표시 중
SOC 직업 분류 기준
| name | starlight |
| version | 1.0.0 |
| description | Starlight - Full-featured documentation theme built on Astro for creating beautiful, accessible, high-performance documentation websites with built-in search, i18n, and customizable components |
Starlight is a full-featured documentation theme built on top of the Astro framework. It provides everything needed to create professional documentation sites with minimal configuration - from built-in search and internationalization to customizable components and dark mode support.
Key Value Proposition: Build beautiful, accessible, high-performance documentation websites with Astro's speed and Starlight's comprehensive feature set. Used by 10,300+ projects with 7,700+ GitHub stars.
┌─────────────────────────────────────────────────────────────────┐
│ Starlight Site │
└─────────────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────┐
│ Content Layer │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────────┐ │
│ │ Markdown │ │ MDX │ │ Markdoc │ │ Frontmatter │ │
│ │ (.md) │ │ (.mdx) │ │ (.mdoc) │ │ (YAML) │ │
│ └──────────┘ └──────────┘ └──────────┘ └───────────────┘ │
└───────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────┐
│ Starlight Features │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────────┐ │
│ │ Sidebar │ │ Search │ │ i18n │ │ Components │ │
│ │Navigation│ │(Pagefind)│ │ (20+lang)│ │ (Tabs,Cards) │ │
│ └──────────┘ └──────────┘ └──────────┘ └───────────────┘ │
└───────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────┐
│ Astro Build │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Static HTML + CSS + Optimized Assets + Sitemap + RSS │ │
│ └──────────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────┐
│ Deployment │
│ Vercel | Netlify | Cloudflare Pages | GitHub Pages | Static │
└───────────────────────────────────────────────────────────────┘
| Layer | Technology | Purpose |
|---|---|---|
| Framework | Astro | Static site generation with island architecture |
| Content | Markdown/MDX/Markdoc | Documentation authoring formats |
| Styling | CSS/Tailwind | Custom theming and styling |
| Search | Pagefind | Client-side full-text search |
| i18n | Built-in | 20+ language translations |
| Syntax Highlighting | Expressive Code | Code blocks with line highlighting |
| Components | Astro Components | Reusable UI elements |
| Build | Vite | Fast development and production builds |
# Create new Starlight project (npm)
npm create astro@latest -- --template starlight
# Create new Starlight project (pnpm)
pnpm create astro --template starlight
# Create new Starlight project (Yarn)
yarn create astro --template starlight
# Create with Tailwind pre-configured
npm create astro@latest -- --template starlight/tailwind
# Create with Markdoc support
npm create astro@latest -- --template starlight/markdoc
# Start development server
npm run dev
# Or with pnpm/yarn
pnpm dev
yarn dev
The development server starts at http://localhost:4321 with hot reload.
# Build static site
npm run build
# Preview production build
npm run preview
my-docs/
├── public/
│ └── favicon.svg # Static favicon
│
├── src/
│ ├── assets/
│ │ └── logo.svg # Site logo
│ │
│ ├── components/
│ │ └── CustomCard.astro # Custom components
│ │
│ ├── content/
│ │ ├── docs/ # Documentation pages
│ │ │ ├── index.mdx # Homepage
│ │ │ ├── getting-started.md
│ │ │ └── guides/
│ │ │ ├── 01-installation.md
│ │ │ └── 02-configuration.md
│ │ │
│ │ ├── i18n/ # Translation files (optional)
│ │ │ ├── ar.json
│ │ │ └── zh-CN.json
│ │ │
│ │ └── content.config.ts # Content collection config
│ │
│ └── styles/
│ └── custom.css # Custom styles
│
├── astro.config.mjs # Astro + Starlight configuration
├── package.json
└── tsconfig.json
// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
export default defineConfig({
integrations: [
starlight({
title: 'My Documentation',
description: 'Learn how to use our product',
// Logo configuration
logo: {
src: './src/assets/logo.svg',
replacesTitle: true, // Hide text title
},
// Social links in header
social: [
{ icon: 'github', label: 'GitHub', href: 'https://github.com/user/repo' },
{ icon: 'discord', label: 'Discord', href: 'https://discord.gg/...' },
],
// Enable edit links
editLink: {
baseUrl: 'https://github.com/user/repo/edit/main/',
},
// Custom CSS
customCss: ['./src/styles/custom.css'],
// Sidebar navigation
sidebar: [
{ slug: 'getting-started' },
{
label: 'Guides',
autogenerate: { directory: 'guides' },
},
{
label: 'Reference',
items: [
{ slug: 'reference/api' },
{ label: 'External', link: 'https://example.com' },
],
},
],
}),
],
});
// Manual sidebar with groups
sidebar: [
// Single page link
{ slug: 'introduction' },
// Group with manual items
{
label: 'Getting Started',
items: [
{ slug: 'installation' },
{ slug: 'configuration' },
],
},
// Auto-generated from directory
{
label: 'Guides',
autogenerate: { directory: 'guides' },
collapsed: true, // Start collapsed
},
// With badge
{
slug: 'api-reference',
badge: { text: 'New', variant: 'tip' },
},
// With translations
{
label: 'Resources',
translations: { 'pt-BR': 'Recursos' },
items: [...],
},
]
logo: {
light: './src/assets/logo-light.svg',
dark: './src/assets/logo-dark.svg',
alt: 'My Project Logo',
}
// Global setting
tableOfContents: {
minHeadingLevel: 2,
maxHeadingLevel: 3
}
// Or disable globally
tableOfContents: false
---
# Required
title: Page Title
# Optional metadata
description: SEO description for the page
slug: custom-url-path
# Layout options
template: doc # 'doc' (default) or 'splash' (landing page)
tableOfContents: false # Disable ToC for this page
# Hero section (for splash pages)
hero:
title: Welcome to My Docs
tagline: Beautiful documentation made easy
image:
file: ../../assets/hero.png
alt: Hero illustration
actions:
- text: Get Started
link: /getting-started/
icon: right-arrow
variant: primary
- text: View on GitHub
link: https://github.com/user/repo
variant: secondary
# Sidebar customization
sidebar:
label: Custom Sidebar Label
order: 1 # Sort order in autogenerated sidebar
badge:
text: Beta
variant: caution # note, tip, caution, danger, success
hidden: false # Hide from sidebar
# Navigation
prev: false # Disable previous page link
next:
link: /next-page/
label: Continue to Next
# Content management
lastUpdated: 2026-01-12
editUrl: false # Disable edit link for this page
draft: true # Exclude from production
pagefind: false # Exclude from search
---
## Headings (H2-H6)
**Bold text** and *italic text* and ~~strikethrough~~
`inline code` for technical terms
[Internal link](/guides/setup/)
[External link](https://example.com)
> Blockquote for important notes
- Unordered list
- Another item
1. Ordered list
2. Second item
:::note
This is a note callout for general information.
:::
:::tip
Helpful tips and best practices go here.
:::
:::caution
Warnings about potential issues.
:::
:::danger
Critical warnings about breaking changes or security issues.
:::
:::tip[Custom Title]
You can customize the callout title.
:::
```javascript title="config.js"
// Basic code block with title
export const config = {
name: 'My App',
};
// Line highlighting and diff markers
function example() {
const highlighted = true;
const alsoHighlighted = true;
const inserted = 'new line'; // Added
const deleted = 'old line'; // Removed
}
npm install @astrojs/starlight
### Details/Accordion
```html
<details>
<summary>Click to expand</summary>
This content is hidden by default.
You can include **Markdown** formatting inside.
</details>
---
title: Using Components
---
import { Tabs, TabItem, Card, CardGrid, LinkCard, Badge, Icon, Steps, FileTree } from '@astrojs/starlight/components';
<Tabs>
<TabItem label="npm">
```bash
npm install package
```
</TabItem>
<TabItem label="pnpm">
```bash
pnpm add package
```
</TabItem>
<TabItem label="yarn">
```bash
yarn add package
```
</TabItem>
</Tabs>
<CardGrid>
<Card title="Getting Started" icon="rocket">
Learn the basics of setting up your project.
</Card>
<Card title="Configuration" icon="setting">
Customize your documentation site.
</Card>
</CardGrid>
<LinkCard
title="View on GitHub"
description="Check out the source code"
href="https://github.com/user/repo"
/>
<Steps>
1. Install the package
```bash
npm install my-package
Configure your project
Add the configuration to your file.
Start building
You're ready to go!
<FileTree>
- src/
- components/
- Header.astro
- Footer.astro
- content/
- docs/
- index.md
- **getting-started.md** (highlighted)
- styles/
- global.css
- astro.config.mjs
- package.json
</FileTree>
<Badge text="New" variant="tip" />
<Badge text="Deprecated" variant="caution" />
<Badge text="v2.0" variant="note" />
<Icon name="star" />
<Icon name="rocket" size="1.5rem" />
<Icon name="github" />
// astro.config.mjs
starlight({
title: 'My Docs',
defaultLocale: 'en',
locales: {
// Root locale (no prefix in URLs)
root: {
label: 'English',
lang: 'en',
},
// Other locales
'zh-cn': {
label: '简体中文',
lang: 'zh-CN',
},
ar: {
label: 'العربية',
dir: 'rtl', // Right-to-left support
},
pt: {
label: 'Português',
lang: 'pt-BR',
},
},
})
src/content/docs/
├── index.md # English (root locale)
├── getting-started.md
├── zh-cn/
│ ├── index.md # Chinese
│ └── getting-started.md
├── ar/
│ ├── index.md # Arabic
│ └── getting-started.md
└── pt/
├── index.md # Portuguese
└── getting-started.md
// src/content/content.config.ts
import { defineCollection } from 'astro:content';
import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders';
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
export const collections = {
docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
i18n: defineCollection({ loader: i18nLoader(), schema: i18nSchema() }),
};
// src/content/i18n/zh-CN.json
{
"search.label": "搜索",
"tableOfContents.onThisPage": "本页目录",
"i18n.untranslatedContent": "此内容尚未翻译。"
}
title: {
en: 'My Documentation',
'zh-CN': '我的文档',
ar: 'وثائقي',
}
/* src/styles/custom.css */
/* Override CSS custom properties */
:root {
--sl-color-accent-low: #1e1b4b;
--sl-color-accent: #4f46e5;
--sl-color-accent-high: #a5b4fc;
--sl-color-text-accent: #818cf8;
--sl-font: 'Inter', sans-serif;
--sl-font-mono: 'Fira Code', monospace;
/* Adjust content width */
--sl-content-width: 50rem;
}
/* Dark mode overrides */
:root[data-theme='dark'] {
--sl-color-accent-low: #312e81;
--sl-color-accent: #6366f1;
}
// astro.config.mjs
customCss: [
'@fontsource/inter/400.css',
'@fontsource/inter/600.css',
'@fontsource/fira-code/400.css',
'./src/styles/custom.css',
]
/* src/styles/custom.css */
:root {
--sl-font: 'Inter', sans-serif;
--sl-font-mono: 'Fira Code', monospace;
}
// 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: ['./src/styles/tailwind.css'],
}),
],
vite: {
plugins: [tailwindcss()],
},
});
/* src/styles/tailwind.css */
@layer base, starlight, theme, components, utilities;
@import '@astrojs/starlight-tailwind';
@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/utilities.css' layer(utilities);
// astro.config.mjs
starlight({
title: 'My Docs',
components: {
// Override the footer
Footer: './src/components/CustomFooter.astro',
// Override social icons
SocialIcons: './src/components/MySocialLinks.astro',
},
})
---
// src/components/CustomFooter.astro
import DefaultFooter from '@astrojs/starlight/components/Footer.astro';
---
<DefaultFooter>
<slot />
</DefaultFooter>
<div class="custom-footer-addition">
<p>Built with Starlight</p>
</div>
---
// src/components/ConditionalFooter.astro
import Default from '@astrojs/starlight/components/Footer.astro';
const isHomepage = Astro.locals.starlightRoute.id === '';
---
{isHomepage ? (
<footer class="custom-homepage-footer">
<p>Welcome to our documentation!</p>
</footer>
) : (
<Default><slot /></Default>
)}
| Component | Location |
|---|---|
Header | Site header with logo and navigation |
Footer | Page footer |
Sidebar | Sidebar navigation |
PageTitle | Page title component |
TableOfContents | Right sidebar table of contents |
SocialIcons | Social media links |
Search | Search component |
ThemeSelect | Dark/light mode toggle |
LanguageSelect | Language switcher |
PageFrame | Overall page layout |
TwoColumnContent | Main content area |
# Install Vercel CLI
npm i -g vercel
# Deploy
vercel
# Install Netlify CLI
npm i -g netlify-cli
# Deploy
netlify deploy --prod
# Build and deploy
npm run build
wrangler pages deploy ./dist
# .github/workflows/deploy.yml
name: Deploy to GitHub Pages
on:
push:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npm run build
- uses: actions/upload-pages-artifact@v3
with:
path: ./dist
deploy:
needs: build
runs-on: ubuntu-latest
permissions:
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- uses: actions/deploy-pages@v4
id: deployment
// astro.config.mjs
export default defineConfig({
site: 'https://user.github.io',
base: '/my-repo/',
integrations: [starlight({ title: 'My Docs' })],
});
Build fails with content collection error:
# Clear Astro cache and rebuild
rm -rf .astro
npm run build
Styles not updating in development:
# Restart dev server with cache clear
npm run dev -- --force
Search not working:
# Ensure pagefind is building
npm run build
# Check dist/_pagefind/ directory exists
i18n pages not found:
defaultLocale matches your root contentComponents not importing:
// Ensure MDX is being used for component imports
// Rename .md to .mdx for component usage
# Update all Astro packages
npx @astrojs/upgrade
# Or with pnpm
pnpm dlx @astrojs/upgrade