readme

2025-06-21 14:22:34 +02:00
parent 1054820ce7
commit 82f4f5a07d
2 changed files with 229 additions and 81 deletions
--- a/README.md
+++ b/README.md
@@ -1,66 +1,107 @@
 # Markdown Blog

-A modern, cross-platform blog system built with **Next.js**, **Markdown**, and **Electron**. Write posts in Markdown, manage content visually, and deploy to web or desktop.
+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.

 ---

-## 🚀 Features
+## 🚀 Key Features

- Write and organize posts in Markdown
- Visual admin dashboard
- Responsive UI (Tailwind CSS)
- Electron desktop app
- Dockerized deployment with persistent storage
- Secure admin password (bcrypt)
+- **📝 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)

 ---

-## 🛠️ Technologies
+## 🛠️ Technology Stack

- Next.js 14
- TypeScript
- Tailwind CSS
- Electron
- Docker
+- **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
+## 📁 Project Structure

 ```
 markdownblog/
-├── posts/           # Markdown blog posts
-├── src/             # Next.js app code
-├── electron/        # Desktop app code
-├── public/          # Static assets
-├── Dockerfile       # Docker configuration
-├── .dockerignore    # Docker ignore rules
-└── manage_container.sh  # Docker management script
+├── src/
+│   ├── app/
+│   │   ├── admin/                 # Admin dashboard pages
+│   │   │   ├── manage/           # Content management interface
+│   │   │   └── page.tsx          # Main admin dashboard
+│   │   ├── api/                  # API routes
+│   │   │   ├── admin/           # Admin API endpoints
+│   │   │   │   ├── delete/      # Delete posts/folders
+│   │   │   │   ├── docker/      # Docker detection
+│   │   │   │   ├── export/      # Export functionality
+│   │   │   │   ├── folders/     # Folder management
+│   │   │   │   ├── password/    # Password management
+│   │   │   │   ├── posts/       # Post CRUD operations
+│   │   │   │   └── upload/      # File upload handling
+│   │   │   └── posts/           # Public post API
+│   │   ├── posts/               # Blog post pages
+│   │   │   └── [...slug]/       # Dynamic post routing
+│   │   ├── globals.css          # Global styles
+│   │   ├── layout.tsx           # Root layout
+│   │   └── page.tsx             # Homepage
+│   └── lib/
+│       ├── markdown.ts          # Markdown processing utilities
+│       └── postsDirectory.ts    # Post directory management
+├── posts/                       # Markdown blog posts
+│   ├── pinned.json             # Pinned posts configuration
+│   ├── welcome.md              # Welcome post
+│   └── mdtest.md               # Test post
+├── public/                      # Static assets (favicons, etc.)
+├── electron/                    # Desktop app configuration
+│   └── main.js                 # Electron main process
+├── Dockerfile                   # Docker container configuration
+├── docker.sh                    # Docker deployment script
+├── entrypoint.sh               # Container entrypoint
+└── package.json                # Dependencies and scripts
 ```

 ---

-## ⚡ Getting Started
+## ⚡ Quick Start

 ### Prerequisites

- Node.js 18+
- npm
- Docker (for containerized deployment)
+- **Node.js 18+**
+- **npm** or **yarn**
+- **Docker** (for containerized deployment)

---
+### Local Development

-## 🖥️ Local Development
+1. **Clone and install**:
+   ```bash
+   git clone <repository-url>
+   cd markdownblog
+   npm install
+   ```

-```bash
-git clone <repo-url>
-cd markdownblog
-npm install
-npm run dev
-```
- Visit [http://localhost:3000](http://localhost:3000) in your browser.
+2. **Start development server**:
+   ```bash
+   npm run dev
+   ```
+   Visit [http://localhost:3000](http://localhost:3000)

-### Build for Production (Local)
+3. **Desktop app development**:
+   ```bash
+   npm run electron-dev
+   ```
+
+### Production Build

 ```bash
 npm run build
@@ -71,53 +112,180 @@ npm start

 ## 🐳 Docker Deployment

-### Build the Docker Image
+### Quick Deployment
+
+Use the provided script for easy deployment:

 ```bash
-docker build -t markdownblog .
+chmod +x docker.sh
+./docker.sh
 ```

-### Run the Container with Persistent Storage
+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

-```bash
-docker run -p 8080:3000 -v markdownblog-posts:/app/docker markdownblog
-```
- The app will be available at [http://localhost:8080](http://localhost:8080)
- All posts are stored persistently in the Docker volume `markdownblog-posts` (mapped to `/app/docker` in the container).
+### Manual Docker Commands

-#### Using a Host Directory for Posts
+1. **Build the image**:
+   ```bash
+   docker build -t markdownblog .
+   ```

-```bash
-docker run -p 8080:3000 -v /absolute/path/to/posts:/app/docker 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 Posts
+## 📝 Writing Blog Posts

- Add Markdown files to the `posts/` directory (or the mounted volume).
- Each post should have frontmatter:
+### Post Structure
+
+Create Markdown files in the `posts/` directory with frontmatter:

 ```markdown
 ---
 title: "Your Post Title"
-date: "YYYY-MM-DD"
-tags: ["tag1", "tag2"]
-summary: "A brief summary of your post"
+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 Password Security
+## 🔐 Admin Dashboard

- Admin password is securely hashed with bcrypt and stored in `posts/admin.json`.
- Never commit your `posts/admin.json` file.
+### 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 
+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.