rattatwinko/markdownblog
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

changed the readme to be sufficient
Some checks failed
Deploy / build-and-deploy (push) Failing after 2s
Details

Browse Source
This commit is contained in:
rattatwinko
2025-06-29 18:11:15 +02:00
parent 4da88915f1
commit baad7309df
2 changed files with 174 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

125
README.md
View File

@@ -1,13 +1,16 @@
# Markdown Blog
# ✍🏼 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.
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
@@ -16,18 +19,21 @@ A modern, feature-rich blog system built with **Next.js 14**, **TypeScript**, an
- **📱 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**: marked, gray-matter, highlight.js
- **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)
---
@@ -35,11 +41,19 @@ A modern, feature-rich blog system built with **Next.js 14**, **TypeScript**, an
```
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
│ │ │ │ ├── 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
@@ -70,10 +84,12 @@ markdownblog/
│ │ │ └── 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
│ │ │ └── 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
@@ -83,8 +99,7 @@ markdownblog/
│ │ ├── 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
│ └── postsDirectory.ts # Post directory management and Rust integration
├── posts/ # Markdown blog posts storage
│ ├── pinned.json # Pinned posts configuration
│ ├── welcome.md # Welcome post with frontmatter
@@ -104,6 +119,7 @@ markdownblog/
├── 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
@@ -116,22 +132,28 @@ markdownblog/
### 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 anchor linking support
- **`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
- **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/markdown.ts`**: Markdown processing with syntax highlighting
- **`src/lib/postsDirectory.ts`**: File system operations and post parsing
- **`src/lib/postsDirectory.ts`**: File system operations and Rust backend integration
#### Desktop App
- **`electron/main.js`**: Electron configuration for desktop application
@@ -140,6 +162,7 @@ markdownblog/
- **`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
---
@@ -149,6 +172,7 @@ markdownblog/
- **Node.js 18+**
- **npm** or **yarn**
- **Rust** (for local development)
- **Docker** (for containerized deployment)
### Local Development
@@ -160,13 +184,20 @@ markdownblog/
npm install
```
2. **Start development server**:
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)
3. **Desktop app development**:
4. **Desktop app development**:
```bash
npm run electron-dev
```
@@ -174,6 +205,10 @@ markdownblog/
### Production Build
```bash
# Build Rust backend
cd markdown_backend && cargo build --release && cd ..
# Build Next.js frontend
npm run build
npm start
```
@@ -192,7 +227,7 @@ chmod +x docker.sh
```
This script will:
- Build the Docker image
- 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
@@ -209,7 +244,7 @@ This script will:
docker run -d \
--name markdownblog \
-p 8080:3000 \
-v markdownblog-posts:/app/docker \
-v markdownblog-posts:/app/posts \
markdownblog
```
@@ -218,7 +253,7 @@ This script will:
docker run -d \
--name markdownblog \
-p 8080:3000 \
-v /path/to/your/posts:/app/docker \
-v /path/to/your/posts:/app/posts \
markdownblog
```
@@ -228,6 +263,7 @@ This script will:
- **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
---
@@ -243,13 +279,14 @@ 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.
Regular Markdown syntax is supported with automatic anchor linking.
### Code Blocks
@@ -262,13 +299,13 @@ console.log("Hello, World!");
- 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
---
@@ -290,23 +327,46 @@ console.log("Hello, World!");
- **📤 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**: DOMPurify for XSS protection
- **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**: highlight.js with GitHub theme
- **Syntax Highlighting**: syntect with GitHub theme
- **Responsive Design**: Mobile-first approach
### Configuration
@@ -315,6 +375,7 @@ console.log("Hello, World!");
- **Tailwind Config**: `tailwind.config.js`
- **TypeScript Config**: `tsconfig.json`
- **PostCSS Config**: `postcss.config.js`
- **Rust Config**: `markdown_backend/Cargo.toml`
---
@@ -329,6 +390,16 @@ 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
```
---
## 📄 License
@@ -342,7 +413,7 @@ MIT License - see [LICENSE](LICENSE) file for details.
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
4. Test thoroughly (both frontend and Rust backend)
5. Submit a pull request
---
@@ -354,8 +425,16 @@ MIT License - see [LICENSE](LICENSE) file for details.
- **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
- **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.
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.