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