@zekari/nextjs-blog

A powerful, feature-rich Next.js blog system with MDX support, built for rapid deployment and easy customization.

✨ Features

• 🎨 Modern UI - Beautiful, responsive design with dark mode support
• 📝 MDX Support - Write in Markdown with React components
• 🔍 Search & Filter - Full-text search and tag-based filtering
• 🎯 Syntax Highlighting - Powered by Shiki with copy-to-clipboard
• 📊 Rich Components - Mermaid diagrams, callouts, link previews
• 🌐 Internationalization - Multi-language support out of the box
• ⚡ Performance - Static generation for blazing-fast load times
• 🔗 Wiki-style Links - [[article]] linking between posts
• 📱 Mobile First - Fully responsive on all devices
• 🚀 Easy Setup - One command to get started

🚀 Quick Start

Option 1: Create New Project

npx @zekari/nextjs-blog create my-blog
cd my-blog
npm run dev

Option 2: Add to Existing Project

npm install @zekari/nextjs-blog
npx @zekari/nextjs-blog init
npm run dev

Visit http://localhost:3000/blog to see your blog!

📦 What's Included

Components (32 total)

Blog Components:

• BlogCard - Post preview cards
• BlogLayout - Layout wrapper with navigation
• BlogFilteredListing - Search and filter interface
• ArticleNavigation - Previous/Next post navigation
• RelatedArticles - Tag-based recommendations
• TableOfContents - Auto-generated TOC
• And 16 more...

MDX Components:

• Callout - 8 types of callout boxes
• Mermaid - Diagram rendering
• LinkPreview - Rich URL previews
• CodeBlock - Syntax highlighted code

UI Components:

• Button, Card, Badge, Alert, ScrollArea
• ThemeToggle, LanguageToggle
• And more...

Library Functions

import {
  getAllPosts,
  getPostBySlug,
  getRelatedPosts,
  filterPosts,
  extractAllTags,
} from '@zekari/nextjs-blog'

📝 Writing Posts

Create a new file in content/blog/en/my-post.md:

---
title: My First Post
date: 2024-11-07
description: This is my first blog post
author: Your Name
tags: [tutorial, guide]
featured: true
---

# Hello World

This is my first blog post using **@zekari/nextjs-blog**!

## Custom Components

<Callout type="info" title="Pro Tip">
You can use custom components in your MDX files!
</Callout>

<Mermaid chart={`
graph TD
    A[Start] --> B[Write]
    B --> C[Publish]
`} />

## Code Example

\`\`\`javascript
const greeting = 'Hello, Blog!'
console.log(greeting)
\`\`\`

## Wiki Links

Link to other posts: [[another-post]]

⚙️ Configuration

Next.js Config

Add to your next.config.js:

/** @type {import('next').NextConfig} */
const nextConfig = {
  pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],

  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'your-domain.com',
      },
    ],
  },

  webpack: (config) => {
    config.resolve.fallback = { fs: false, path: false }
    return config
  },
}

module.exports = nextConfig

Tailwind Config

Add to your tailwind.config.js:

module.exports = {
  content: [
    './app/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
    './node_modules/@zekari/nextjs-blog/dist/**/*.{js,mjs}',
  ],
  darkMode: 'class',
  theme: {
    extend: {
      // Use the theme configuration from the template
    },
  },
  plugins: [
    require('@tailwindcss/typography'),
  ],
}

🎨 Customization

Custom Theme

All components use Tailwind CSS and can be customized through your tailwind.config.js.

Custom Components

Import and use components directly:

import { BlogCard, getAllPosts } from '@zekari/nextjs-blog'

export default async function CustomPage() {
  const posts = await getAllPosts('en')

  return (
    <div className="grid grid-cols-3 gap-4">
      {posts.map(post => (
        <BlogCard key={post.slug} post={post} locale="en" />
      ))}
    </div>
  )
}

Custom MDX Components

Create your own MDX components:

import { MDXComponents } from '@zekari/nextjs-blog'

const customComponents = {
  ...MDXComponents,
  // Add your custom components
  CustomComponent: (props) => <div {...props} />,
}

📚 API Reference

getAllPosts(locale: string)

Get all blog posts for a specific locale.

const posts = await getAllPosts('en')
// Returns: BlogListItem[]

getPostBySlug(slug: string, locale: string)

Get a single post by slug.

const post = await getPostBySlug('my-post', 'en')
// Returns: BlogPost

getRelatedPosts(currentPost: BlogPost, allPosts: BlogPost[], limit?: number)

Get related posts based on tags.

const related = await getRelatedPosts(post, allPosts, 3)
// Returns: BlogPost[]

filterPosts(posts: BlogPost[], search: string, selectedTags: string[])

Filter posts by search term and tags.

const filtered = filterPosts(allPosts, 'tutorial', ['guide'])
// Returns: BlogPost[]

🌐 Multi-language Support

Add content in different languages:

content/
  blog/
    en/
      post-1.md
      post-2.md
    zh-CN/
      post-1.md
      post-2.md

Use the locale parameter in functions:

const englishPosts = await getAllPosts('en')
const chinesePosts = await getAllPosts('zh-CN')

📖 Custom MDX Components Reference

Callout

<Callout type="info | warning | success | error | tip | note | question | danger"
         title="Title"
         defaultOpen={true}>
  Content here
</Callout>

Mermaid

<Mermaid chart={`
  graph LR
    A --> B
    B --> C
`} />

LinkPreview

<LinkPreview url="https://example.com" />

Wiki Links

[[post-slug]]
[[post-slug|Custom Display Text]]

🚢 Deployment

Vercel

1. Push your code to GitHub
2. Import project to Vercel
3. Deploy automatically

Other Platforms

npm run build
npm start

🛠️ CLI Commands

Create new project

npx @zekari/nextjs-blog create my-blog

Initialize in existing project

npx @zekari/nextjs-blog init

Update blog system

npx @zekari/nextjs-blog update

📦 Required Dependencies

The following dependencies are automatically installed with init:

• @mdx-js/loader, @mdx-js/react, @next/mdx
• gray-matter, next-mdx-remote
• remark-gfm, rehype-pretty-code, shiki
• mermaid, framer-motion, lucide-react
• @radix-ui/react-scroll-area, @radix-ui/react-slot
• @tailwindcss/typography
• next-themes, date-fns
• clsx, tailwind-merge, class-variance-authority

🤝 Contributing

Contributions are welcome! This is a personal project but feel free to submit issues or suggestions.

📄 License

MIT © Zekari

🙏 Credits

Built with:

• Next.js
• MDX
• Tailwind CSS
• Shiki
• Mermaid
• And many other amazing open-source projects

Happy blogging! 🚀

For issues and support, visit: GitHub Repository