markdownblog/README.md

✍🏼 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

---

🛠️ 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
│   │   │   ├── 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
│   │   │       ├── stream/      # Server-Sent Events for real-time updates
│   │   │       │   └── 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
│   │   └── page.tsx             # Homepage with post listing
│   └── lib/                     # Utility libraries
│       └── postsDirectory.ts    # Post directory management and Rust integration
├── 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
├── 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:

   git clone <repository-url>
   cd markdownblog
   npm install
   

2. Build Rust backend:

   cd markdown_backend
   cargo build --release
   cd ..
   

3. Start development server:

   npm run dev
   

   Visit http://localhost:3000

4. Desktop app development:

   npm run electron-dev
   

Production Build

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

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:

   docker build -t markdownblog .
   

2. Run with persistent storage:

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

3. Using host directory:

   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:

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

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

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

---

🎨 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

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

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

---

📄 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 (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

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.