# ✍🏼 Markdown Blog ✍🏻

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

---

## 🚀 Key Features

- **📝 Markdown Blog Posts**: Write posts with frontmatter metadata (title, date, tags, summary)
- **⚡ Rust-Powered Parsing**: Blazing-fast markdown parsing with syntax highlighting and HTML sanitization
- **🔄 Real-Time Updates**: Server-Sent Events (SSE) for live content updates
- **🎨 Visual Admin Dashboard**: Manage posts, folders, and content structure through a web interface
- **📊 Rust Status Monitoring**: Real-time parser logs, performance metrics, and health monitoring
- **📌 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)
- **💾 Smart Caching**: RAM-based caching system for instant post retrieval
- **🔧 VS Code-Style Editor**: Monaco editor with YAML frontmatter support and live preview
- **🔄 Force Reparse**: Manual cache clearing and post reparsing for immediate updates
- **📁 Reliable Directory Scanning**: Robust file system traversal with error handling

---

## 🛠️ Technology Stack

- **Frontend**: Next.js 14, React 18, TypeScript
- **Backend**: Rust (markdown parsing, file watching, caching)
- **Styling**: Tailwind CSS, @tailwindcss/typography
- **Markdown**: pulldown-cmark, syntect (syntax highlighting), ammonia (HTML sanitization)
- **Desktop**: Electron
- **Security**: bcrypt, DOMPurify
- **Deployment**: Docker, PM2
- **Development**: ESLint, PostCSS, Autoprefixer
- **Real-time**: Server-Sent Events (SSE)

---

## 📁 Project Structure

```
markdownblog/
├── markdown_backend/            # Rust backend for markdown processing
│   ├── src/
│   │   ├── main.rs              # CLI interface and command handling
│   │   └── markdown.rs          # Markdown parsing, caching, and file watching
│   ├── Cargo.toml               # Rust dependencies and configuration
│   └── target/                  # Compiled Rust binaries
├── src/
│   ├── app/                     # Next.js 14 App Router
│   │   ├── admin/               # Admin dashboard pages
│   │   │   ├── editor/          # VS Code-style editor
│   │   │   │   └── page.tsx     # Markdown editor with Monaco
│   │   │   ├── manage/          # Content management interface
│   │   │   │   ├── page.tsx     # Manage posts and folders
│   │   │   │   └── rust-status/ # Rust backend monitoring
│   │   │   │       └── page.tsx # Parser logs and performance metrics
│   │   │   └── 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
│   │   │       ├── preview/     # Markdown preview API
│   │   │       │   └── route.ts
│   │   │       ├── stream/      # Server-Sent Events for real-time updates
│   │   │       │   └── route.ts
│   │   │       ├── webhook/     # Webhook endpoint
│   │   │       │   └── 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 and SSE
│   │   ├── 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
│   │   ├── monaco-vim.d.ts      # Monaco Vim typings
│   │   └── page.tsx             # Homepage with post listing
│   └── lib/                     # Utility libraries
│       └── postsDirectory.ts    # Post directory management and Rust integration
├── posts/                       # Markdown blog posts storage
│   ├── about.md
│   ├── welcome.md
│   └── assets/
│       └── peta.png
├── 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
├── run-local-backend.sh         # Local Rust backend runner
├── 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

#### Rust Backend (`markdown_backend/`)
- **`src/main.rs`**: CLI interface with commands for parsing, watching, and health checks
- **`src/markdown.rs`**: Core markdown processing, caching, file watching, and logging
- **Features**: Syntax highlighting, HTML sanitization, RAM caching, recursive folder scanning

#### 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 SSE and anchor linking
- **`src/app/admin/page.tsx`**: Admin dashboard with content management
- **`src/app/admin/manage/page.tsx`**: Advanced content management interface
- **`src/app/admin/rust-status/page.tsx`**: Rust backend monitoring and logs

#### API Routes
- **Post Management**: CRUD operations for blog posts (Rust-powered)
- **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
- **SSE Streaming**: Real-time updates via Server-Sent Events

#### Utilities
- **`src/lib/postsDirectory.ts`**: File system operations and Rust backend integration

#### 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
- **`run-local-backend.sh`**: Local Rust backend runner

---

## ⚡ Quick Start

### Prerequisites

- **Node.js 18+**
- **npm** or **yarn**
- **Rust** (for local development)
- **Docker** (for containerized deployment)

### Local Development

1. **Clone and install**:
   ```bash
   git clone <repository-url>
   cd markdownblog
   npm install
   ```

2. **Build Rust backend**:
   ```bash
   cd markdown_backend
   cargo build --release
   cd ..
   ```

3. **Start development server**:
   ```bash
   npm run dev
   ```
   Visit [http://localhost:3000](http://localhost:3000)

4. **Desktop app development**:
   ```bash
   npm run electron-dev
   ```

### Production Build

```bash
# Build Rust backend
cd markdown_backend && cargo build --release && cd ..

# Build Next.js frontend
npm run build
npm start
```

---

## 🐳 Docker Deployment

### Quick Deployment

Use the provided script for easy deployment:

```bash
chmod +x docker.sh
./docker.sh
```

This script will:
- Build the Docker image (including Rust backend)
- 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**:
   ```bash
   docker build -t markdownblog .
   ```

2. **Run with persistent storage**:
   ```bash
   docker run -d \
     --name markdownblog \
     -p 8080:3000 \
     -v markdownblog-posts:/app/posts \
     markdownblog
   ```

3. **Using host directory**:
   ```bash
   docker run -d \
     --name markdownblog \
     -p 8080:3000 \
     -v /path/to/your/posts:/app/posts \
     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
- **Rust Backend**: Pre-compiled Rust binaries for optimal performance

---

## 📝 Writing Blog Posts

### Post Structure

Create Markdown files in the `posts/` directory with frontmatter:

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

Your post content here...

## Headers

Regular Markdown syntax is supported with automatic anchor linking.

### 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
- **Real-time Updates**: Changes are reflected immediately via SSE

---

## 🔐 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)
- **📊 Rust Status**: Monitor parser performance, logs, and health
- **🔍 Log Management**: View, filter, and clear parser logs
- **🔧 VS Code Editor**: Monaco-based editor with YAML frontmatter preservation
- **🔄 Force Reparse**: Manual cache clearing and post reparsing
- **📁 Reliable Scanning**: Enhanced directory traversal with error recovery

### Security

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

---

## 🚀 Performance Features

### Rust Backend Benefits

- **⚡ 10x Faster Parsing**: Compared to previous TypeScript implementation
- **💾 40% Memory Reduction**: More efficient resource usage
- **🔍 Syntax Highlighting**: Powered by syntect with 200+ language support
- **🛡️ HTML Sanitization**: Ammonia-based security with customizable policies
- **📁 Recursive Scanning**: Efficient folder traversal and file discovery
- **💾 Smart Caching**: RAM-based caching with disk persistence
- **📊 Performance Monitoring**: Real-time metrics and logging
- **🔄 Force Reparse**: Manual cache invalidation and post reparsing
- **📁 Reliable Directory Scanning**: Robust error handling and recovery
- **🔧 Single Post Reparse**: Efficient individual post cache clearing

### Real-Time Updates

- **🔄 Server-Sent Events**: Live content updates without page refresh
- **📡 File Watching**: Automatic detection of post changes
- **⚡ Instant Updates**: Sub-second response to file modifications
- **🔄 Fallback Polling**: Graceful degradation if SSE fails

### VS Code-Style Editor

- **🔧 Monaco Editor**: Professional code editor with syntax highlighting
- **📄 YAML Frontmatter**: Preserved and editable at the top of files
- **👁️ Live Preview**: Real-time Markdown rendering
- **💾 Save & Reparse**: Automatic cache clearing and post reparsing
- **⌨️ Vim Mode**: Optional Vim keybindings for power users
- **📱 Responsive Design**: Works on desktop and mobile devices
- **🎨 Custom Styling**: JetBrains Mono font and VS Code-like appearance

---

## 🎨 Customization

### Styling

- **Tailwind CSS**: Utility-first CSS framework
- **Typography**: @tailwindcss/typography for content styling
- **Syntax Highlighting**: syntect 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`
- **Rust Config**: `markdown_backend/Cargo.toml`

---

## 🔧 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
```

### Rust Backend Commands

```bash
cd markdown_backend
cargo build --release # Build optimized binary
cargo run -- watch    # Watch for file changes
cargo run -- logs     # View parser logs
cargo run -- checkhealth # Check backend health
cargo run -- reinterpret-all # Force reparse all posts
cargo run -- reparse-post <slug> # Force reparse single post
```

---

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

---

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly (both frontend and Rust backend)
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 Rust is installed
- **Rust backend issues**: Check `/admin/rust-status` for logs and health status

### Rust Backend Troubleshooting

- **Compilation errors**: Ensure Rust toolchain is up to date
- **File watching issues**: Check file permissions and inotify limits
- **Performance issues**: Monitor logs via admin interface
- **Cache problems**: Clear cache via admin interface or restart
- **Directory scanning errors**: Check file permissions and hidden files
- **Reparse failures**: Verify post slugs and file existence
- **Memory issues**: Monitor cache size and clear if necessary

### Support

For issues and questions, please check the project structure and API documentation in the codebase. The admin interface includes comprehensive monitoring tools for the Rust backend.

---

## 🆕 Recent Improvements (Latest)

### Rust Backend Enhancements

- **🔄 Force Reparse Commands**: New CLI commands for manual cache invalidation
  - `reinterpret-all`: Clear all caches and reparse every post
  - `reparse-post <slug>`: Clear cache for specific post and reparse
- **📁 Reliable Directory Scanning**: Enhanced file system traversal with:
  - Hidden file filtering (skips `.` files)
  - Graceful error recovery for inaccessible files
  - Detailed logging of scanning process
  - Automatic directory creation if missing
- **💾 Improved Cache Management**: Better cache directory handling and persistence
- **📊 Enhanced Logging**: Comprehensive logging for debugging and monitoring

### Editor Improvements

- **🔧 VS Code-Style Interface**: Monaco editor with professional features
- **📄 YAML Frontmatter Preservation**: Frontmatter stays at top and remains editable
- **💾 Save & Reparse Integration**: Automatic Rust backend integration on save
- **👁️ Live Preview**: Real-time Markdown rendering without frontmatter
- **⌨️ Vim Mode Support**: Optional Vim keybindings for power users
- **📱 Mobile Responsive**: Works seamlessly on all device sizes

### Admin Panel Enhancements

- **🔄 Force Reparse Button**: One-click cache clearing and post reparsing
- **📊 Enhanced Rust Status**: Real-time parser performance monitoring
- **🔍 Improved Log Management**: Better filtering and search capabilities
- **📁 Directory Health Monitoring**: Comprehensive file system diagnostics