← Back

Hello world

一个基于 React Router v7、fumadocs-mdx、Vite 8、Tailwind CSS 4 和 Bun 的静态博客生成器

这个项目是一个面向静态托管的个人博客生成器，目标是用尽量少的运行时复杂度完成文章、代码高亮、图片画廊和静态预渲染。

技术栈

  • React Router v7 负责路由、页面组织和静态预渲染
  • fumadocs-mdx 负责读取并编译本地 Markdown / MDX 内容
  • Shiki 负责代码块语法高亮
  • Vite 8 负责开发服务器和生产构建
  • Tailwind CSS 4 负责样式系统
  • Oxc 负责 lint 和 format
  • Bun 负责依赖管理和脚本运行

内容组织

博客文章放在 content/blog 目录中，每篇文章使用 Markdown 或 MDX 编写，并通过 frontmatter 描述标题、摘要和日期。

---
title: 文章标题
description: 文章描述
date: 2026-04-25
---

正文内容

文件路径会直接映射为文章 URL：

  • content/blog/hello-world.mdx -> /blog/hello-world
  • content/blog/foo/index.mdx -> /blog/foo

静态生成

项目默认不依赖运行时服务器。构建阶段会扫描 content/blog 下的文章，并预渲染首页、博客列表、文章详情和 Gallery 页面。

bun run build

构建产物输出到 build/client，可以直接部署到支持静态文件托管的平台。

图片放在 content/gallery 目录，支持 avif、jpeg、jpg、png 和 webp。

构建或开发启动前会执行 Gallery 生成脚本：

  • 原图统一转存为 WebP
  • 自动生成 40x40 WebP 缩略图
  • 生成图片元数据文件供 Gallery 组件使用
  • Gallery 组件使用缩略图做模糊加载，再渐进显示原图
bun run build:gallery

生成产物位于 public/gallery，不会作为源内容维护。

页面功能

目前项目包含这些核心页面：

  • /：首页
  • /blog：博客文章列表
  • /blog/*：文章详情页
  • /gallery：图片画廊

文章详情页支持 MDX 渲染、代码高亮、中文标题字体和统一的内容排版。Gallery 页面支持图片懒加载、模糊占位和点击查看大图。

开发与验证

常用开发命令：

bun install
bun run dev

交付前优先运行：

bun run typecheck
bun run lint
bun run format:check
bun run build