361 lines
12 KiB
Markdown
361 lines
12 KiB
Markdown
# 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**:
|
|
```bash
|
|
git clone <repository-url>
|
|
cd markdownblog
|
|
npm install
|
|
```
|
|
|
|
2. **Start development server**:
|
|
```bash
|
|
npm run dev
|
|
```
|
|
Visit [http://localhost:3000](http://localhost:3000)
|
|
|
|
3. **Desktop app development**:
|
|
```bash
|
|
npm run electron-dev
|
|
```
|
|
|
|
### Production Build
|
|
|
|
```bash
|
|
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
|
|
- 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/docker \
|
|
markdownblog
|
|
```
|
|
|
|
3. **Using host directory**:
|
|
```bash
|
|
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:
|
|
|
|
```markdown
|
|
---
|
|
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](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. |