npm package: @fenz007/nextjs-blog
Description: A powerful Next.js blog system with MDX support, featuring search, tags, TOC, and rich components
Author: Zekari
Latest version: 1.0.0

# @zekari/nextjs-blog

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

[![npm version](https://img.shields.io/npm/v/@zekari/nextjs-blog.svg)](https://www.npmjs.com/package/@zekari/nextjs-blog)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## ✨ 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

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

### Option 2: Add to Existing Project

```bash
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

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

## 📝 Writing Posts

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

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

```javascript
/** @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`:

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

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

```tsx
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.

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

### getPostBySlug(slug: string, locale: string)

Get a single post by slug.

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

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

Get related posts based on tags.

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

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

Filter posts by search term and tags.

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

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

## 📖 Custom MDX Components Reference

### Callout

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

### Mermaid

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

### LinkPreview

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

### Wiki Links

```markdown
[[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

```bash
npm run build
npm start
```

## 🛠️ CLI Commands

### Create new project

```bash
npx @zekari/nextjs-blog create my-blog
```

### Initialize in existing project

```bash
npx @zekari/nextjs-blog init
```

### Update blog system

```bash
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](https://nextjs.org/)
- [MDX](https://mdxjs.com/)
- [Tailwind CSS](https://tailwindcss.com/)
- [Shiki](https://shiki.matsu.io/)
- [Mermaid](https://mermaid.js.org/)
- And many other amazing open-source projects

---

**Happy blogging!** 🚀

For issues and support, visit: [GitHub Repository](https://github.com/JoshHong947/nextjs-blog-package)