Blog

For the blog feature, we are using the Fumadocs MDX library.

Fumadocs MDX is a library that allows you to create blog posts in Markdown and use MDX components to add rich content to your blog posts.

🏗️ Blog System Architecture

NEXTDEVKIT's blog system is built with the following structure:

src/
├── content/
│   └── blog/
│       ├── writing-a-new-blog-post-here.md
│       ├── writing-a-new-blog-post-here.zh.md
│       ├── md-test.md
│       └── md-test.zh.md
├── app/
│   └── [locale]/
│       └── (marketing)/
│           └── blog/
│               ├── page.tsx          # Blog listing page
│               ├── layout.tsx        # Blog layout
│               └── [...slug]/
│                   └── page.tsx      # Individual blog post
├── components/
│   └── blog/
│       ├── mdx-components.tsx        # Custom MDX components
│       ├── toc.tsx                   # Table of contents
│       └── go-to-top.tsx             # Go to top button
├── config/
│   └── marketing/
│       └── blog.ts                   # Blog configuration
└── source.config.ts                 # Blog collection schema

📝 Writing a Blog Post

To create a new blog post, you need to create a new Markdown file in the src/content/blog/ directory.

The file name should be the slug of the blog post.

if you want the url to be https://your-app.com/blog/my-first-post, then the file name should be my-first-post.mdx.

The file should contain the following frontmatter:

---
title: "My First Blog Post"
description: "This is a description of my first blog post"
createdAt: 2024-01-15T10:00:00Z
updatedAt: 2024-01-15T10:00:00Z
author: "John Doe"
image: "/blog/my-first-post.jpg"
tags: ["tutorial", "getting-started"]
keywords: "nextdevkit, saas, tutorial, getting-started"

Blog Post Schema

Every blog post must include these frontmatter fields:

Field	Type	Required	Description
`title`	string	✅	Blog post title
`description`	string	✅	Brief description for SEO
`keywords`	string	❌	SEO keywords (comma-separated)
`createdAt`	date	✅	Publication date
`updatedAt`	date	✅	Last update date
`tags`	string[]	❌	Category tags
`author`	string	✅	Author name
`image`	string	❌	Cover image URL

The title and description and keywords is also used for SEO.

After the frontmatter block, you can write the content of the blog post in MDX.

⚙️ Blog Configuration

Source Configuration

The blog system is configured in source.config.ts:

src/source.config.ts

import { defineCollections } from "fumadocs-mdx/config";
import { z } from "zod";

export const blogs = defineCollections({
  type: "doc",
  dir: "src/content/blog",
  schema: (ctx) => {
    return z.object({
      title: z.string(),
      description: z.string(),
      // ... other fields
    });
  },
});

Blog Configuration

Blog settings are defined in src/config/marketing/blog.ts:

src/config/marketing/blog.ts

export interface BlogConfig {
  title: string;
  description: string;
  placeholderImage: string;
}

export async function getBlogConfig(): Promise<BlogConfig> {
  const t = await getTranslations("blog");

  return {
    title: t("title"),
    description: t("description"),
    placeholderImage: "/marketing/feature-techstacks.png",
  };
}

🌐 Multi-Language Support

NEXTDEVKIT blog system supports multiple languages using file naming conventions:

File Naming Convention

Default locale (English): filename.md
Other locales: filename.{locale}.md

Example: Multi-Language Blog Post

English version: getting-started.md

---
title: "Getting Started with NEXTDEVKIT"
description: "Learn how to build modern SaaS applications"
createdAt: 2024-01-15T10:00:00Z
updatedAt: 2024-01-15T10:00:00Z
tags: ["tutorial", "getting-started"]
author: "NEXTDEVKIT Team"
---

# Getting Started with NEXTDEVKIT

Welcome to NEXTDEVKIT! This guide will help you build modern SaaS applications.

## What is NEXTDEVKIT?

NEXTDEVKIT is a complete toolkit for building SaaS applications...

Chinese version: getting-started.zh.md

---
title: "NEXTDEVKIT 快速入门"
description: "学习如何使用 NEXTDEVKIT 构建现代 SaaS 应用"
createdAt: 2024-01-15T10:00:00Z
updatedAt: 2024-01-15T10:00:00Z
tags: ["教程", "快速入门"]
author: "NEXTDEVKIT 团队"
---

# NEXTDEVKIT 快速入门

欢迎使用 NEXTDEVKIT！本指南将帮助您构建现代 SaaS 应用程序。

## 什么是 NEXTDEVKIT？

NEXTDEVKIT 是一个完整的 SaaS 应用程序构建工具包...

🎨 Rich Content Components

Custom MDX Components

NEXTDEVKIT provides custom MDX components in src/components/blog/mdx-components.tsx:

const components = {
  // Enhanced headings with custom styling
  h1: ({ className, ...props }) => (
    <h1 className={cn("font-heading my-8 text-2xl md:text-[1.8rem]", className)} {...props} />
  ),
  // ... other components
};

📑 Table of Contents

Automatic TOC Generation

NEXTDEVKIT automatically generates a table of contents from your blog post headings:

export function DashboardTableOfContents({ items }: TocProps) {
  const itemIds = React.useMemo(
    () => items
      .map((item) => item.url)
      .filter(Boolean)
      .map((id) => id?.split("#")[1]),
    [items]
  );
  
  const activeHeading = useActiveItem(itemIds);
  
  return (
    <div className="space-y-2">
      <Tree items={items} activeItem={activeHeading} />
    </div>
  );
}

TOC Features

Auto-generated from heading structure
Active heading highlighting
Smooth scrolling to sections
Responsive design for mobile/desktop
Intersection observer for active states

🔧 Customization

Adding Custom Components

Create custom MDX components:

export function VideoEmbed({ url, title }) {
  return (
    <div className="my-8">
      <iframe
        src={url}
        title={title}
        className="w-full aspect-video rounded-lg"
        allowFullScreen
      />
    </div>
  );
}

export function Newsletter() {
  return (
    <div className="my-8 p-6 bg-blue-50 rounded-lg">
      <h3 className="text-lg font-semibold mb-2">Subscribe to Our Newsletter</h3>
      <p className="text-gray-600 mb-4">Get the latest NEXTDEVKIT updates and tips.</p>
      <div className="flex gap-2">
        <input
          type="email"
          placeholder="Enter your email"
          className="flex-1 px-3 py-2 border rounded-md"
        />
        <button className="px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700">
          Subscribe
        </button>
      </div>
    </div>
  );
}

Add to MDX components:

import { VideoEmbed, Newsletter } from './custom-components';

const components = {
  ...defaultMdxComponents,
  VideoEmbed,
  Newsletter,
  // ... other components
};

🔧 Troubleshooting

Common Issues

Posts Not Showing:

Check frontmatter syntax
Verify file extension (.md or .mdx)
Ensure proper date format
Check locale configuration

MDX Component Errors:

Verify component imports
Check JSX syntax in markdown
Ensure components are properly exported

Styling Issues:

Check CSS class names
Verify Tailwind configuration
Review MDX component styling

Build Errors:

Validate frontmatter schema
Check for missing required fields
Verify image paths exist

🎯 Next Steps

Now that you understand the blog system, explore these related features:

On this page