综合练习

把 sa-intro 到 sa-when 串起来：用 Astro 搭一个文档页原型——MDX 正文、导航、一个客户端搜索或主题切换岛，静态 build 后可部署。证明你不仅会 react-essentials 组件，还能为 内容交付 选对栈。

学习目标

• 独立完成 Astro 项目从 scaffold 到 dist/ 静态产物
• 应用 Content Collections 或 Markdown 组织至少 2 页
• 衔接 ft-deploy 与 html-css-essentials 语义结构

任务说明

必做

1. npm create astro@latest，选 Docs/Starlight 或 Minimal + 自建布局
2. 两页以上 Markdown/MDX，例如：
   • /docs/react-essentials（链到 /tracks/react-essentials）
   • /docs/vue-essentials（链到 /tracks/vue-essentials）
3. 一个交互岛（React 或 Svelte）：站内搜索过滤标题，或 dark/light toggle
4. astro build 成功；本地 preview 可点通导航
5. README：build 命令、output 目录、若上 Netlify 的 publish 路径

选做

• Tailwind + prose 排版（见 sa-styling）
• 对比同内容纯 nextjs-essentials 页的 JS 体积（Lighthouse）
• 用 fetch 在 build 时拉一条公开 API 展示（见 sa-data）

推荐流程

1. 定信息架构（侧栏 + 2 文档页）
2. 写 MDX，交叉链 nextjs / frontend-toolchain / html-css 各一处
3. 加 client:visible 岛，避免整页 hydrate
4. npm run build → 检查 dist 体积
5. （可选）推 Git，接 Cloudflare Pages 预览

禁止：把整个侧栏做成 client:load 的 React 根；禁止 secrets 进仓库。

自检清单

• 未访问页面 不应 加载搜索/主题岛的 JS（Network 验证）
• 外链均为 /tracks/... 或官方文档，无编造 slug
• scoped / prose 样式不破坏 MD 标题层级（对照 html-css 语义课）
• README 说明与 ft-vite 脚本习惯一致（dev / build / preview）
• 能口头解释：为何此练习用 Astro 而非 Next 全栈

反思题

1. 若改为 SvelteKit 静态 export，你要改哪几步？
2. 若内容改由 Java API 提供，你还会全量 SSG 吗？
3. Eleventy 能否完成同原型？差在哪一项？

与路线图

完成后回到 /roadmaps/frontend，勾选 Svelte / Astro / 静态站 / SSG 相关节点。继续深入可结合 next-mdx 对比本站课时渲染管线。

小结

内容在 MD，交互在岛，产物在 dist——Astro 文档站的合格交付不过如此。 本 track 完结；主栈仍建议熟练 React/Next，本课补足 选型与轻量内容站 能力。