配置问题

本文档解答 Tiebo 项目配置和使用过程中常见的问题。

基础配置

Q: 如何修改网站标题和描述？

A: 在 astro.config.mjs 文件中修改：

starlight({
  title: '你的网站标题',
  description: '你的网站描述',
  // 其他配置...
})

Q: 如何添加自定义 CSS？

A: 在 astro.config.mjs 中指定自定义 CSS 文件：

starlight({
  customCss: ['./src/styles/global.css', './src/styles/custom.css'],
  // 其他配置...
})

侧边栏配置

Q: 如何设置默认折叠的分组？

A: 在侧边栏配置中添加 collapsed: true：

sidebar: [
  {
    label: '分组名称',
    collapsed: true, // 默认折叠
    items: [
      // 分组内容...
    ]
  }
]

Q: 如何创建多级嵌套菜单？

A: 在 items 数组中嵌套更多对象：

sidebar: [
  {
    label: '主分组',
    items: [
      {
        label: '子分组',
        items: [
          { label: '页面', slug: 'path/to/page' }
        ]
      }
    ]
  }
]

Q: 如何自动生成侧边栏目录？

A: 使用 autogenerate 配置：

{
  label: '自动生成',
  autogenerate: {
    directory: 'docs/api',
    collapsed: false
  }
}

Q: 如何自定义页面在侧边栏中的顺序？

A: 在页面的 front matter 中设置 sidebar.order：

---
title: 页面标题
sidebar:
  order: 1  # 数字越小越靠前
---

主题和样式

Q: 如何修改主题颜色？

A: 在 CSS 文件中修改 CSS 变量：

:root {
  --color-primary: #8B4513;        /* 主色调 */
  --color-secondary: #D2691E;      /* 辅助色 */
  --color-accent: #CD853F;         /* 强调色 */
}

Q: 如何添加自定义字体？

A: 1. 在 fonts.css 中导入字体：

@import url('https://fonts.googleapis.com/css2?family=FontName&display=swap');

在 CSS 中使用：

:root {
  --font-family-body: 'FontName', sans-serif;
}

Q: 如何禁用暗色模式？

A: 在 CSS 中移除暗色模式相关的样式，或者在配置中禁用主题切换功能。

内容配置

Q: 如何设置首页？

A: 创建 src/content/docs/index.mdx 文件并设置 template: splash：

---
title: 网站标题
description: 网站描述
template: splash
hero:
  tagline: 副标题
  actions:
    - text: 开始使用
      link: /guides/
---

Q: 如何隐藏页面不在侧边栏中显示？

A: 在 front matter 中设置：

---
title: 隐藏页面
sidebar:
  hidden: true
---

Q: 如何设置页面重定向？

A: 创建重定向页面：

---
title: 重定向
template: redirect
redirect: /new-path/
---

Markdown 配置

Q: 如何启用数学公式？

A: 在 astro.config.mjs 中配置：

import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';

export default defineConfig({
  integrations: [starlight({...})],
  markdown: {
    remarkPlugins: [remarkMath],
    rehypePlugins: [[rehypeKatex, {
      // KaTeX 配置选项
    }]]
  }
});

Q: 如何自定义代码高亮主题？

A: 在 CSS 中覆盖代码高亮样式：

/* 行内代码 */
code {
  background-color: var(--color-code-bg);
  color: var(--color-code-text);
}

/* 代码块 */
pre {
  background-color: var(--color-code-bg);
  border: 1px solid var(--color-code-border);
}

构建配置

Q: 如何配置自定义域名？

A: 在 astro.config.mjs 中设置：

export default defineConfig({
  site: 'https://yourdomain.com',
  integrations: [
    starlight({
      // 配置...
    })
  ]
});

Q: 如何优化构建性能？

A: 1. 启用压缩：

export default defineConfig({
  vite: {
    build: {
      minify: 'terser',
      terserOptions: {
        compress: {
          drop_console: true
        }
      }
    }
  }
});

配置图片优化：

export default defineConfig({
  image: {
    domains: ['yourdomain.com'],
    format: ['webp', 'avif']
  }
});

多语言配置

Q: 如何配置多语言网站？

A: 在 astro.config.mjs 中配置：

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

Q: 如何为不同语言创建内容？

A: 在 src/content/docs/ 下创建对应的语言目录：

src/content/docs/
├── zh-CN/
│   ├── index.mdx
│   └── guides/
└── en-US/
    ├── index.mdx
    └── guides/

部署配置

Q: 如何配置环境变量？

A: 1. 创建 .env 文件：

PUBLIC_SITE_URL=https://yourdomain.com
PUBLIC_API_KEY=your-api-key

在代码中使用：

const siteUrl = import.meta.env.PUBLIC_SITE_URL;

Q: 如何配置不同平台的部署？

Vercel: 添加 vercel.json
Netlify: 添加 netlify.toml
GitHub Pages: 配置 GitHub Actions

调试问题

Q: 如何启用调试模式？

A: 启动开发服务器时添加调试标志：

DEBUG=astro:* npm run dev

Q: 如何查看详细的构建日志？

A: 构建时添加详细输出：

npm run build -- --verbose

Q: 如何解决热重载不工作的问题？

A: 1. 确保没有防火墙阻拦 2. 尝试重启开发服务器 3. 检查文件监听限制：

# macOS/Linux
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf

通过以上配置解决方案，你可以更好地定制和使用 Tiebo 项目。如果还有其他问题，可以查看 Starlight 官方文档或寻求社区帮助。