Skip to content

MIGRATION.md

Latest commit

 

History

History
190 lines (145 loc) · 4.46 KB

MIGRATION.md

File metadata and controls

190 lines (145 loc) · 4.46 KB

FlightNG Docs 迁移指南

迁移状态：✅ 已完成

本文档记录从 MkDocs Material 迁移到 Astro + Starlight 的进度和待办事项。

已完成 ✅

项目结构

  • 创建 Astro + Starlight 项目基础结构
  • 配置 package.json 依赖
  • 配置 astro.config.mjs
  • 配置 TypeScript
  • 删除 MkDocs 相关文件 (mkdocs.yml, docs/, theme/, requirements.txt)
  • 将 Astro 项目移动到根目录

国际化

  • 配置中文/英文双语支持
  • 设置中文为默认语言
  • 配置侧边栏翻译

内容迁移

  • 首页 (splash 模板 + Hero 组件)
  • Fidelity X 概览页面
  • 快速开始文档
  • 功能特性文档
  • 支持的硬件文档
  • 固件烧录文档
  • CLI 命令参考
  • 配置指南索引
  • PID 调参文档
  • 速率曲线文档
  • 安全系统文档
  • atbetaflight 文档
  • 赞助页面

样式和组件

  • 自定义 CSS 主题
  • 自定义 Hero 组件 (Apple 风格)
  • 移动端优化样式
  • 深色/浅色模式支持
  • GitHub Actions 自动部署配置

待完成 📋

必须完成

  1. 安装依赖并构建测试

    npm install
npm run dev

  2. 验证所有链接

    • 内部链接格式已更新为 /docs/zh/... 和 /docs/en/...
    • 需要手动验证所有页面链接正常

可选优化

  • 添加搜索功能配置（Starlight 内置，但可能需要调优）
  • 添加 RSS feed（如果需要博客功能）
  • 配置 SEO 元数据
  • 添加 sitemap 生成
  • 配置 Google Analytics 或其他分析
  • 优化图片加载（使用 Astro 的图片优化）

架构对比

特性 MkDocs Material Astro + Starlight
构建速度 中等 极快
移动端体验 良好（但 fullpage 有问题） 优秀（原生响应式）
自定义程度 中等 极高
组件系统 Jinja2 模板 Astro/React/Vue/Svelte
国际化 插件支持 内置支持
搜索 插件支持 内置 Pagefind
主题 Material Design 可完全自定义

目录结构

.
├── public/
│   └── assets/
│       └── images/          # 静态图片资源
├── src/
│   ├── assets/              # Logo SVG 文件
│   ├── components/          # 自定义组件
│   │   └── Hero.astro       # 自定义首页 Hero
│   ├── content/
│   │   └── docs/
│   │       ├── zh/          # 中文文档
│   │       │   ├── index.mdx
│   │       │   ├── fydelix/
│   │       │   ├── atbetaflight/
│   │       │   └── sponsor.mdx
│   │       └── en/          # 英文文档
│   │           ├── index.mdx
│   │           ├── fydelix/
│   │           ├── atbetaflight/
│   │           └── sponsor.mdx
│   ├── styles/
│   │   └── custom.css       # 自定义样式
│   └── content.config.ts    # 内容集合配置
├── astro.config.mjs         # Astro 配置
├── package.json
└── tsconfig.json

启动命令

# 安装依赖
npm install

# 开发模式 (http://localhost:4321)
npm run dev

# 生产构建
npm run build

# 预览生产构建
npm run preview

部署

构建输出在 dist/ 目录，可以部署到：

  • GitHub Pages
  • Vercel
  • Netlify
  • Cloudflare Pages
  • 任何静态托管服务

GitHub Pages 配置

astro.config.mjs 已配置：

site: 'https://flightng.github.io',
base: '/docs',

如果部署到其他域名，请相应修改这两个值。

注意事项

  1. Markdown 语法差异

    • MkDocs 的 !!! note 改为 Starlight 的 :::note
    • MkDocs 的 ??? question 改为 :::tip[question] 或删除折叠功能
    • { .md-button } 类名需要改为内联样式或自定义组件

  2. 链接格式

    • 相对链接改为绝对链接 /docs/zh/...
    • 英文版使用 /docs/en/...

  3. 图标

    • Material Icons 改为 Starlight 内置图标或 emoji

  4. 首页

    • 使用 template: splash 和自定义 Hero 组件
    • CardGrid 组件替代 MkDocs 的 grid cards

下一步任务 (Handoff)

如果 Claude 会话中断，下一个 Claude 需要：

  1. 阅读本文档了解迁移状态
  2. 运行 npm install && npm run dev 测试
  3. 修复任何发现的问题
  4. 完成可选优化项

最后更新：2026-01-13