文档内容管理和主题定制

内容管理系统

1. 内容集合

Astro 的内容集合系统让文档管理变得简单高效：

import { defineCollection, z } from 'astro:content';

const docs = defineCollection({
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.date().optional(),
    updatedDate: z.date().optional(),
    tags: z.array(z.string()).optional(),
  }),
});

export const collections = { docs };

2. 文档组织

推荐的文档目录结构：

src/content/docs/
  ├── getting-started/
  │   ├── installation.md
  │   └── configuration.md
  ├── guides/
  │   ├── content-management.md
  │   └── deployment.md
  └── api/
      ├── endpoints.md
      └── authentication.md

3. 元数据管理

使用 frontmatter 管理文档元数据：

---
title: API 端点
description: API 端点完整参考
pubDate: 2024-01-15
tags: ['api', 'reference']
---

主题定制

1. 自定义样式

基础样式覆盖

:root {
  --sl-color-accent: #0077CC;
  --sl-color-text: #2C3E50;
  --sl-font-system: system-ui, -apple-system, sans-serif;
}

/* 自定义组件样式 */
.custom-card {
  background: var(--sl-color-gray-1);
  border-radius: 8px;
  padding: 1.5rem;
  margin: 1rem 0;
}

主题变体

starlight({
  customCss: [
    './src/styles/custom.css',
    './src/styles/theme-dark.css',
  ],
});

2. 组件系统

创建可重用组件

---
interface Props {
  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
  path: string;
  auth?: boolean;
}

const { method, path, auth = false } = Astro.props;
---

<div class="api-endpoint">
  <span class={`method ${method.toLowerCase()}`}>{method}</span>
  <code class="path">{path}</code>
  {auth && <span class="auth">🔒 需要认证</span>}
</div>

<style>
.api-endpoint {
  display: flex;
  align-items: center;
  gap: 1rem;
  padding: 1rem;
  background: var(--sl-color-gray-1);
  border-radius: 6px;
}

.method {
  padding: 0.25rem 0.5rem;
  border-radius: 4px;
  font-weight: bold;
}

.method.get { background: #61affe; }
.method.post { background: #49cc90; }
.method.put { background: #fca130; }
.method.delete { background: #f93e3e; }
</style>

使用自定义组件

---
title: API 文档
---

# API 端点

<ApiEndpoint method="GET" path="/api/users" />

## 用户认证

<ApiEndpoint method="POST" path="/api/auth/login" auth={true} />

3. 导航定制

自定义侧边栏

starlight({
  sidebar: [
    {
      label: '入门指南',
      items: [
        { label: '快速开始', link: '/getting-started' },
        {
          label: '基础教程',
          collapsed: true,
          items: [
            { label: '安装', link: '/tutorials/installation' },
            { label: '配置', link: '/tutorials/configuration' },
          ],
        },
      ],
    },
    {
      label: 'API 参考',
      autogenerate: { directory: 'api' },
    },
  ],
});

自定义页头

<div class="custom-header">
  <div class="version-selector">
    <select>
      <option value="v1">v1.0.0</option>
      <option value="v2">v2.0.0</option>
    </select>
  </div>
  <div class="header-links">
    <a href="/support">支持</a>
    <a href="/github">GitHub</a>
  </div>
</div>

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

高级功能

1. 国际化支持

starlight({
  defaultLocale: 'zh-cn',
  locales: {
    'zh-cn': {
      label: '简体中文',
      lang: 'zh-CN',
    },
    'en': {
      label: 'English',
      lang: 'en',
    },
  },
});

2. 插件集成

集成评论系统

import Giscus from '@giscus/react';

<Giscus
  repo="username/repo"
  repoId="R_xxx"
  category="Announcements"
  categoryId="xxx"
  mapping="pathname"
  reactionsEnabled="1"
  emitMetadata="0"
  theme="light"
/>

添加搜索增强

starlight({
  search: {
    provider: 'algolia',
    config: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
    },
  },
});

最佳实践

主题定制
- 保持品牌一致性
- 确保良好的暗色模式支持
- 优化移动端显示
内容组织
- 使用清晰的文件命名规范
- 保持合理的目录深度
- 定期更新文档内容
组件开发
- 组件职责单一
- 保持可复用性
- 提供完整的类型定义

下一步

完成内容管理和主题定制后，你可以：

优化构建流程
配置自动部署
设置性能监控
添加用户分析

在下一章中，我们将详细介绍如何部署和优化你的文档网站。