rattatwinko/markdownblog
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e3d8ba101772bcf3e78c0abd0d5854f28d8ac58c
markdownblog/README.md
rattatwinko 21f13ef8ae Enhance blog features and improve backend functionality 
- Added a VS Code-style editor with YAML frontmatter support and live preview.
- Implemented force reparse functionality for immediate updates of posts.
- Improved directory scanning with error handling and automatic directory creation.
- Introduced new CLI commands for cache management: `reinterpret-all` and `reparse-post`.
- Enhanced logging for better debugging and monitoring of the Rust backend.
- Updated README to reflect new features and improvements.
2025-07-05 22:23:58 +02:00

503 lines
19 KiB
Markdown
Raw Blame History

# ✍🏼 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
Reference in New Issue View Git Blame Copy Permalink