Markdown Blog

A modern, feature-rich blog system built with Next.js 14, TypeScript, and Markdown. Features include a visual admin dashboard, Electron desktop app, Docker deployment, and secure content management.

---

🚀 Key Features

• 📝 Markdown Blog Posts: Write posts with frontmatter metadata (title, date, tags, summary)
• 🎨 Visual Admin Dashboard: Manage posts, folders, and content structure through a web interface
• 📌 Pin Posts: Pin important posts to the top of your blog
• 📁 Folder Organization: Organize posts in nested folders
• 🖥️ Desktop App: Electron-based desktop application
• 🐳 Docker Support: Containerized deployment with persistent storage
• 🔒 Secure Admin: Password-protected admin interface with bcrypt hashing
• 📱 Responsive Design: Mobile-friendly UI with Tailwind CSS
• 🎯 Content Management: Drag & drop file uploads, post editing, and deletion
• 📦 Export Functionality: Export all posts as tar.gz archive (Docker only)

---

🛠️ Technology Stack

• Frontend: Next.js 14, React 18, TypeScript
• Styling: Tailwind CSS, @tailwindcss/typography
• Markdown: marked, gray-matter, highlight.js
• Desktop: Electron
• Security: bcrypt, DOMPurify
• Deployment: Docker, PM2
• Development: ESLint, PostCSS, Autoprefixer

---

📁 Project Structure

markdownblog/
├── src/
│   ├── app/
│   │   ├── admin/                 # Admin dashboard pages
│   │   │   ├── manage/           # Content management interface
│   │   │   └── page.tsx          # Main admin dashboard
│   │   ├── api/                  # API routes
│   │   │   ├── admin/           # Admin API endpoints
│   │   │   │   ├── delete/      # Delete posts/folders
│   │   │   │   ├── docker/      # Docker detection
│   │   │   │   ├── export/      # Export functionality
│   │   │   │   ├── folders/     # Folder management
│   │   │   │   ├── password/    # Password management
│   │   │   │   ├── posts/       # Post CRUD operations
│   │   │   │   └── upload/      # File upload handling
│   │   │   └── posts/           # Public post API
│   │   ├── posts/               # Blog post pages
│   │   │   └── [...slug]/       # Dynamic post routing
│   │   ├── globals.css          # Global styles
│   │   ├── layout.tsx           # Root layout
│   │   └── page.tsx             # Homepage
│   └── lib/
│       ├── markdown.ts          # Markdown processing utilities
│       └── postsDirectory.ts    # Post directory management
├── posts/                       # Markdown blog posts
│   ├── pinned.json             # Pinned posts configuration
│   ├── welcome.md              # Welcome post
│   └── mdtest.md               # Test post
├── public/                      # Static assets (favicons, etc.)
├── electron/                    # Desktop app configuration
│   └── main.js                 # Electron main process
├── Dockerfile                   # Docker container configuration
├── docker.sh                    # Docker deployment script
├── entrypoint.sh               # Container entrypoint
└── package.json                # Dependencies and scripts

---

⚡ Quick Start

Prerequisites

• Node.js 18+
• npm or yarn
• Docker (for containerized deployment)

Local Development

1. Clone and install:

   git clone <repository-url>
   cd markdownblog
   npm install
   

2. Start development server:

   npm run dev
   

   Visit http://localhost:3000

3. Desktop app development:

   npm run electron-dev
   

Production Build

npm run build
npm start

---

🐳 Docker Deployment

Quick Deployment

Use the provided script for easy deployment:

chmod +x docker.sh
./docker.sh

This script will:

• Build the Docker image
• Create a persistent volume for posts
• Run the container on port 8080
• Copy built-in posts to the volume

Manual Docker Commands

1. Build the image:

   docker build -t markdownblog .
   

2. Run with persistent storage:

   docker run -d \
     --name markdownblog \
     -p 8080:3000 \
     -v markdownblog-posts:/app/docker \
     markdownblog
   

3. Using host directory:

   docker run -d \
     --name markdownblog \
     -p 8080:3000 \
     -v /path/to/your/posts:/app/docker \
     markdownblog
   

Docker Features

• Persistent Storage: Posts are stored in Docker volumes
• Export Functionality: Export all posts as tar.gz (Docker only)
• Auto-restart: Container automatically restarts on failure
• Built-in Posts: Welcome and test posts included

---

📝 Writing Blog Posts

Post Structure

Create Markdown files in the posts/ directory with frontmatter:

---
title: "Your Post Title"
date: "2024-01-15"
tags: ["technology", "programming", "web"]
summary: "A brief description of your post content"
---

Your post content here...

## Headers

Regular Markdown syntax is supported.

### Code Blocks

```javascript
console.log("Hello, World!");

Lists

• Item 1
• Item 2
  • Nested item

### Post Organization

- **Root Level**: Posts directly in `posts/` folder
- **Folders**: Create subdirectories for organization
- **Nested Structure**: Support for unlimited nesting levels

---

## 🔐 Admin Dashboard

### Access

- **URL**: `/admin`
- **Default Username**: `admin`
- **Password**: Set via API or environment variable

### Features

- **📝 Create Posts**: Rich text editor with live Markdown preview
- **📁 Manage Folders**: Create and organize content structure
- **📌 Pin Posts**: Pin important posts to the top
- **🔄 Edit Posts**: In-place editing with frontmatter support
- **🗑️ Delete Content**: Remove posts and folders
- **📤 Upload Files**: Drag & drop Markdown files
- **🔐 Change Password**: Secure password management
- **📦 Export Posts**: Download all posts as archive (Docker only)

### Security

- **Password Hashing**: bcrypt with salt
- **Session Management**: Local storage-based authentication
- **Input Sanitization**: DOMPurify for XSS protection
- **File Validation**: Markdown file type checking

---

## 🎨 Customization

### Styling

- **Tailwind CSS**: Utility-first CSS framework
- **Typography**: @tailwindcss/typography for content styling
- **Syntax Highlighting**: highlight.js with GitHub theme
- **Responsive Design**: Mobile-first approach

### Configuration

- **Next.js Config**: `next.config.js`
- **Tailwind Config**: `tailwind.config.js`
- **TypeScript Config**: `tsconfig.json`
- **PostCSS Config**: `postcss.config.js`

---

## 🔧 Development Scripts

```bash
npm run dev          # Start development server
npm run build        # Build for production
npm run start        # Start production server
npm run lint         # Run ESLint
npm run electron     # Start Electron app
npm run electron-dev # Start Electron with dev server

---

📄 License

MIT License - see LICENSE file for details.

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

---

🐛 Troubleshooting

Common Issues

• Port conflicts: Change port in docker.sh or Docker run command
• Permission errors: Ensure docker.sh is executable (chmod +x docker.sh)
• Volume issues: Check Docker volume exists and has proper permissions
• Build failures: Ensure Node.js version is 18+ and all dependencies are installed

Support

For issues and questions, please check the project structure and API documentation in the codebase.