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/                      # Next.js 14 App Router
│   │   ├── admin/               # Admin dashboard pages
│   │   │   ├── manage/          # Content management interface
│   │   │   │   └── page.tsx     # Manage posts and folders
│   │   │   └── page.tsx         # Main admin dashboard
│   │   ├── api/                 # API routes (Next.js API routes)
│   │   │   ├── admin/           # Admin API endpoints
│   │   │   │   ├── delete/      # Delete posts/folders
│   │   │   │   │   └── route.ts
│   │   │   │   ├── docker/      # Docker detection
│   │   │   │   │   └── route.ts
│   │   │   │   ├── export/      # Export functionality (Docker)
│   │   │   │   │   └── route.ts
│   │   │   │   ├── exportlocal/ # Export functionality (Local)
│   │   │   │   │   └── route.ts
│   │   │   │   ├── folders/     # Folder management
│   │   │   │   │   ├── details/ # Folder details API
│   │   │   │   │   │   └── route.ts
│   │   │   │   │   └── route.ts
│   │   │   │   ├── password/    # Password management
│   │   │   │   │   └── route.ts
│   │   │   │   ├── posts/       # Post CRUD operations
│   │   │   │   │   ├── move/    # Move posts between folders
│   │   │   │   │   │   └── route.ts
│   │   │   │   │   ├── raw/     # Get raw post content
│   │   │   │   │   │   └── route.ts
│   │   │   │   │   ├── route.ts
│   │   │   │   │   └── size/    # Get post size info
│   │   │   │   │       └── route.ts
│   │   │   │   └── upload/      # File upload handling
│   │   │   │       └── route.ts
│   │   │   └── posts/           # Public post API
│   │   │       ├── [slug]/      # Dynamic post API routes
│   │   │       │   └── route.ts
│   │   │       └── route.ts     # List all posts
│   │   ├── posts/               # Blog post pages
│   │   │   └── [...slug]/       # Dynamic post routing (catch-all)
│   │   │       └── page.tsx     # Individual post page with anchor linking
│   │   ├── AboutButton.tsx      # About page button component
│   │   ├── BadgeButton.tsx      # Badge display component
│   │   ├── globals.css          # Global styles and Tailwind imports
│   │   ├── HeaderButtons.tsx    # Header navigation buttons
│   │   ├── highlight-github.css # Code syntax highlighting styles
│   │   ├── layout.tsx           # Root layout with metadata
│   │   ├── MobileNav.tsx        # Mobile navigation component
│   │   └── page.tsx             # Homepage with post listing
│   └── lib/                     # Utility libraries
│       ├── markdown.ts          # Markdown processing with marked.js
│       └── postsDirectory.ts    # Post directory management and parsing
├── posts/                       # Markdown blog posts storage
│   ├── pinned.json             # Pinned posts configuration
│   ├── welcome.md              # Welcome post with frontmatter
│   ├── mdtest.md               # Test post with various markdown features
│   ├── anchor-test.md          # Test post for anchor linking
│   └── ii/                     # Example nested folder structure
├── public/                      # Static assets
│   ├── android-chrome-192x192.png
│   ├── android-chrome-512x512.png
│   ├── apple-touch-icon.png
│   ├── favicon-16x16.png
│   ├── favicon-32x32.png
│   ├── favicon.ico
│   └── site.webmanifest
├── electron/                    # Desktop application
│   └── main.js                 # Electron main process configuration
├── Dockerfile                   # Docker container configuration
├── docker.sh                    # Docker deployment script
├── entrypoint.sh               # Container entrypoint script
├── next-env.d.ts               # Next.js TypeScript definitions
├── next.config.js              # Next.js configuration
├── package-lock.json           # npm lock file
├── package.json                # Dependencies and scripts
├── postcss.config.js           # PostCSS configuration
├── tailwind.config.js          # Tailwind CSS configuration
├── tsconfig.json               # TypeScript configuration
└── LICENSE                     # MIT License

Key Components

Frontend (Next.js 14 App Router)

• src/app/page.tsx: Homepage with responsive post listing and search
• src/app/posts/[...slug]/page.tsx: Individual post pages with anchor linking support
• src/app/admin/page.tsx: Admin dashboard with content management
• src/app/admin/manage/page.tsx: Advanced content management interface

API Routes

• Post Management: CRUD operations for blog posts
• Folder Management: Create, delete, and organize content structure
• Authentication: Password management and validation
• Export: Docker and local export functionality
• Upload: Drag & drop file upload handling

Utilities

• src/lib/markdown.ts: Markdown processing with syntax highlighting
• src/lib/postsDirectory.ts: File system operations and post parsing

Desktop App

• electron/main.js: Electron configuration for desktop application

Deployment

• Dockerfile: Multi-stage build for production deployment
• docker.sh: Automated deployment script with volume management
• entrypoint.sh: Container initialization and post setup

---

⚡ 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.