基于文件的博客系统

从基础到高级，全面掌握 NextDevKit 博客模块，学习 MDX 写作、内容管理和高级功能定制。

NextDevKit 使用 Fumadocs MDX 构建博客系统，提供了强大的内容创作和管理能力。

博客是现代网站不可缺少的功能模块。无论是分享技术心得，还是公司发布产品更新，一个功能完善的博客系统都能带来巨大价值，通过 SEO 优化可以带来更多的自然搜索流量。

NextDevKit 内置了基于 MDX 的现代化博客系统，让你专注于内容创作。

🤔 什么是 MDX？

MDX 核心概念

MDX (Markdown for JSX) 是 Markdown 的超集，允许你在 Markdown 文档中直接使用 JSX 组件。这意味着你可以：

保持 Markdown 的简洁性：继续使用熟悉的 Markdown 语法
增强交互能力：嵌入 React 组件实现复杂功能
统一开发体验：内容和组件使用相同的技术栈
类型安全：享受 TypeScript 的完整支持

MDX vs 传统 Markdown

传统 Markdown 的局限：

# 我的博客文章
这是一段普通文本。

![图片](./image.png)

MDX 的强大之处：

# 我的博客文章
这是一段普通文本。

<Image 
  src="/blog/my-image.png" 
  alt="高清图片" 
  width={800} 
  height={400}
  priority
/>

<VideoEmbed url="https://www.youtube.com/watch?v=..." />

🏗️ NextDevKit 博客架构

目录结构

NextDevKit 的博客系统采用基于文件的内容管理方式：

gpt-embeddings.mdx

gpt-embeddings.zh.mdx

vector-database.mdx

vector-database.zh.mdx

page.tsx

layout.tsx

page.tsx

mdx-components.tsx

toc.tsx

go-to-top.tsx

核心组件说明：

src/content/blog/：存放所有博客 MDX 文件
app/[locale]/(marketing)/blog/：博客页面路由和布局
components/blog/：博客专用的 React 组件
多语言支持：.mdx (英文) 和 .zh.mdx (中文) 文件

技术栈

NextDevKit 博客系统基于以下技术：

Fumadocs MDX：MDX 解析和渲染引擎
Next.js 15：应用框架和路由系统
TypeScript：类型安全的开发体验
Tailwind CSS：样式系统
Rehype/Remark：内容处理插件

✍️ 创建你的第一篇博客

理解 Frontmatter 与 Fumadocs 配置

Frontmatter Schema 定义

NextDevKit 在 source.config.ts 中定义了博客的 Zod Schema，确保每篇文章的元数据格式正确：

source.config.ts

export const blogs = defineCollections({
  type: "doc",
  dir: "src/content/blog",
  schema: (ctx) => {
    return z.object({
      title: z.string(),                    // 必填：文章标题
      description: z.string(),              // 必填：文章描述
      keywords: z.string().optional(),      // 可选：SEO 关键词
      createdAt: z.date(),                  // 必填：创建日期
      updatedAt: z.date(),                  // 必填：更新日期
      tags: z.array(z.string()).optional(), // 可选：标签数组
      author: z.string(),                   // 必填：作者信息
      image: z.string().optional(),         // 可选：封面图片
      slug: z.string().default(/* 自动生成 */),   // 自动：URL 路径
      locale: z.string().default(/* 自动检测 */), // 自动：语言区域
    });
  },
});

智能字段处理

自动 Slug 生成：

slug: z.string().default(ctx.path.split("/").pop()?.split(".")[0])

文件 nextjs-guide.zh.mdx → slug: "nextjs-guide"

自动语言检测：

locale: z.string().default(() => {
  const locale = ctx.path.split("/").pop()?.split(".")[1];
  if (locale === "md" || locale === "mdx") {
    return appConfig.i18n.defaultLocale; // 默认 "en"
  }
  return locale; // "zh", "ja" 等
})

完整 Frontmatter 示例

每篇博客都以 YAML Frontmatter 开始，定义文章的元数据：

src/content/blog/my-first-post.zh.mdx

---
title: 我的第一篇博客
description: "这是我使用 NextDevKit 创建的第一篇博客文章，介绍了基础的 MDX 写作方法。"
keywords: "nextjs 博客, mdx 教程, nextdevkit"
createdAt: 2025-01-15T10:00:00+08:00
updatedAt: 2025-01-15T10:00:00+08:00
tags: ["nextjs", "博客", "教程"]
author: "你的名字"
image: "/blog/my-first-post.png"
# slug 和 locale 会自动生成，无需手动填写
---

# 欢迎来到我的博客！

多语言支持

NextDevKit 支持多语言博客。为同一篇文章创建不同语言版本：

src/content/blog/
├── my-post.mdx        # 英文版本
└── my-post.zh.mdx     # 中文版本

当然你也可以添加更多的语言版本。

📊 博客管理和优化

文章组织策略

按时间组织：

src/content/blog/
├── 2025-01-nextjs-tutorial.mdx
├── 2025-02-react-patterns.mdx
└── 2025-03-typescript-tips.mdx

按主题组织：

src/content/blog/
├── nextjs-complete-guide.mdx
├── react-best-practices.mdx
└── typescript-advanced.mdx

标签和分类系统

使用标签对文章进行分类：

tags: ["nextjs", "react", "typescript", "教程"]

标签命名建议：

技术标签：nextjs, react, typescript, css
类型标签：教程, 指南, 案例研究, 新闻
难度标签：初学者, 中级, 高级
主题标签：前端, 后端, 全栈, 设计
业务标签：AI, 云计算, 数据库, 安全, 运维

SEO 优化

标题优化：

title: "Next.js 15 完全指南：从入门到实战 (2025)"

描述优化：

description: "深入学习 Next.js 15 的新特性，包括 App Router、Server Components、并行路由等。本指南提供实战案例和最佳实践。"

关键词策略：

keywords: "nextjs 15, app router, server components, react, nextjs 教程"

图片优化策略

图片命名规范：

public/blog/
├── nextjs-guide/
│   ├── hero-image.png
│   ├── app-router-diagram.svg
│   └── performance-chart.webp
└── react-patterns/
    ├── component-tree.png
    └── state-flow.svg