NEXTDEVKIT Blog System

NEXTDEVKIT includes a powerful blog system built with Fumadocs MDX, allowing you to create rich, interactive blog content using Markdown and MDX components. This guide will walk you through everything you need to know about creating and managing blog content in your NEXTDEVKIT project.

🏗️ Blog System Architecture

NEXTDEVKIT's blog system is built with a well-organized structure that separates content, components, and configuration:

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

This architecture provides a clean separation of concerns, making it easy to manage content, customize components, and maintain your blog system.

📝 Writing a Blog Post

Creating a new blog post is straightforward. Simply create a new Markdown file in the src/content/blog/ directory with the desired slug as the filename.

File Naming Convention

The file name determines the URL slug for your blog post:

• For URL https://your-app.com/blog/my-first-post → filename: my-first-post.md
• For URL https://your-app.com/blog/getting-started → filename: getting-started.md

Frontmatter Structure

Every blog post must include frontmatter with the following structure:

---
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:

The title, description, and keywords fields are used for SEO optimization, helping your blog posts rank better in search engines.

⚙️ Blog Configuration

Source Configuration

The blog system is configured in source.config.ts using Fumadocs' collection system:

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(),
      createdAt: z.date(),
      updatedAt: z.date(),
      author: z.string(),
      tags: z.array(z.string()).optional(),
      keywords: z.string().optional(),
      image: z.string().optional(),
    });
  },
});

Blog Configuration

Blog settings are defined in 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",
  };
}

This configuration allows you to customize the blog's appearance and behavior while maintaining internationalization support.

🌐 Multi-Language Support

NEXTDEVKIT's blog system supports multiple languages using a simple file naming convention, making it easy to create content for different audiences.

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 for enhanced content presentation:

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} />
  ),
  h2: ({ className, ...props }) => (
    <h2 className={cn("font-heading mt-12 mb-4 text-xl md:text-2xl", className)} {...props} />
  ),
  // Custom code blocks with syntax highlighting
  pre: ({ className, ...props }) => (
    <pre className={cn("mb-4 mt-6 overflow-x-auto rounded-lg border bg-zinc-950 py-4", className)} {...props} />
  ),
  // Enhanced links with external link indicators
  a: ({ className, ...props }) => (
    <a className={cn("font-medium underline underline-offset-4", className)} {...props} />
  ),
  // ... other components
};

These components ensure consistent styling and enhanced functionality across all blog posts.

📑 Table of Contents

Automatic TOC Generation

NEXTDEVKIT automatically generates a table of contents from your blog post headings using the toc.tsx component:

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

The table of contents includes several advanced features:

• Auto-generated from heading structure
• Active heading highlighting based on scroll position
• Smooth scrolling to sections when clicked
• Responsive design that adapts to mobile and desktop
• Intersection observer for accurate active states

🔧 Customization

Adding Custom Components

You can create custom MDX components to enhance your blog posts:

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>
  );
}

Then add these components to your MDX components:

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

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

Using Custom Components in Blog Posts

Once registered, you can use these components directly in your MDX files:

# My Blog Post

Here's some regular markdown content.

<VideoEmbed url="https://www.youtube.com/embed/dQw4w9WgXcQ" title="Rick Roll" />

More content here...

<Newsletter />

🔧 Troubleshooting

Common Issues and Solutions

Posts Not Showing:

• Check frontmatter syntax for proper YAML formatting
• Verify file extension is .md or .mdx
• Ensure proper date format (ISO 8601)
• Check locale configuration matches file naming

MDX Component Errors:

• Verify component imports are correct
• Check JSX syntax in markdown content
• Ensure components are properly exported
• Validate component props match expected types

Styling Issues:

• Check CSS class names are correctly applied
• Verify Tailwind configuration includes all necessary classes
• Review MDX component styling for conflicts
• Test responsive design on different screen sizes

Build Errors:

• Validate frontmatter schema matches configuration
• Check for missing required fields in frontmatter
• Verify image paths exist in the public directory
• Ensure all imports are properly resolved

🚀 Advanced Features

Code Syntax Highlighting

NEXTDEVKIT includes syntax highlighting for code blocks:

// This will be automatically highlighted
function greet(name: string) {
  return `Hello, ${name}!`;
}

Image Optimization

Use Next.js Image component for optimized images:

![Blog Image](/blog/my-image.jpg)

Interactive Elements

Add interactive elements using React components:

<button onClick={() => alert('Hello!')}>Click me</button>

🔗 Related Resources

• Fumadocs Documentation
• MDX Documentation
• Next.js Blog Tutorial
• Markdown Guide

🎯 Next Steps

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

• 📚 Documentation System - Learn about the docs structure
• 🎨 UI Components - Discover available components
• 🌐 Internationalization - Implement multi-language support
• 🔍 SEO Optimization - Improve search engine visibility

The NEXTDEVKIT blog system provides a powerful foundation for creating engaging, interactive content. With its combination of Markdown simplicity and React component flexibility, you can build a blog that truly stands out.

📝 Best Practices

Content Organization

• Use descriptive filenames that match your URL structure
• Organize posts by date or category in subdirectories if needed
• Keep frontmatter consistent across all posts
• Use meaningful tags for better content discovery

SEO Optimization

• Write compelling titles and descriptions
• Use relevant keywords naturally in content
• Include alt text for images
• Optimize images for web performance
• Use proper heading hierarchy (H1, H2, H3, etc.)

Performance Considerations

• Optimize images before uploading
• Use code splitting for large components
• Minimize bundle size by importing only necessary components
• Test loading performance on different devices

With these tools and best practices, you're ready to create a compelling blog experience for your NEXTDEVKIT application!