Content
# Misonote Markdown - Modern Documentation Preview System
[](https://github.com/leeguooooo/markdown-site)
[](https://github.com/leeguooooo/markdown-site)
[](https://github.com/leeguooooo/markdown-site/blob/main/LICENSE)
[](https://github.com/leeguooooo)
[English](./README.en.md) | [日本語](./README.ja.md) |
A modern Markdown document management and preview system, supporting Mermaid diagrams, global search, directory navigation, and more.
<div align="center">
**🐳 One-click Docker Run | 📱 Responsive Design | 🔐 Secure Authentication | 💬 Comment System**
[](https://github.com/leeguooooo/markdown-site#-one-click-run-recommended)
[](https://hub.docker.com/r/leeguo/misonote-markdown)
[](./DOCKER-QUICKSTART.md)
[](https://your-demo-url.com)
</div>
> 🚀 **If this project helps you, please give it a ⭐ Star!**
## 🎯 Why Choose This Project?
- 🐳 **One-click Run**: Docker image ready to use, no Node.js installation required
- ✅ **Multi-architecture Support**: Supports Intel/AMD and Apple Silicon chips
- ✅ **Zero-configuration Deployment**: One command to deploy, automatic environment variable configuration
- ✅ **Production-ready**: Built-in PM2 support, suitable for production environments
- ✅ **Secure and Reliable**: Base64 encoding solves special character issues, bcrypt password encryption
- ✅ **Modern Tech Stack**: Next.js 15 + React 19 + TypeScript
## ✨ Features
- 📝 **Markdown Support**: Complete support for GitHub Flavored Markdown
- 📊 **Mermaid Diagrams**: Built-in support for flowcharts, sequence diagrams, Gantt charts, and more
- 🔍 **Global Search**: Powerful full-text search with keyword highlighting
- 🌲 **Directory Navigation**: Tree structure display, supports folder collapse and expansion
- 📱 **Responsive Design**: Adapts to desktop and mobile devices
- 🔐 **Secure Management**: JWT authentication, password hash protection
- ✏️ **Online Editing**: Powerful Markdown editor with real-time preview
- 📁 **File Management**: Drag-and-drop upload, creation, editing, and deletion of documents
## 🚀 Quick Start
### 🐳 One-click Run (Recommended)
**No Node.js installation, no code cloning, one command to run!**
```bash
# Method 1: Use default temporary password (admin123)
docker run -d \
-p 3001:3001 \
-v $(pwd)/docs:/app/docs \
-v $(pwd)/data:/app/data \
leeguo/misonote-markdown:latest
# Method 2: Set custom password at startup (recommended)
docker run -d \
--name misonote-markdown \
-p 3001:3001 \
-e ADMIN_PASSWORD=admin123 \
-v $(pwd)/docs:/app/docs \
-v $(pwd)/data:/app/data \
leeguo/misonote-markdown:latest
```
**Access immediately**: http://localhost:3001
**Admin Dashboard**: http://localhost:3001/admin
**Default Password**: admin123 (if ADMIN_PASSWORD is not set)
#### 🔧 Common Management Commands
```bash
# Check container status
docker ps
# View application logs
docker logs misonote-markdown
# Stop application
docker stop misonote-markdown
# Restart application
docker restart misonote-markdown
# Enter container
docker exec -it misonote-markdown sh
# Delete container
docker rm -f misonote-markdown
```
#### 🔧 Using Docker Compose (Recommended for Production)
```bash
# Download configuration file
curl -O https://raw.githubusercontent.com/leeguooooo/markdown-site/main/docker-compose.yml
# Start service
docker-compose up -d
# Check status
docker-compose ps
```
#### 📦 Docker Hub Image Information
- **Image Address**: `leeguo/misonote-markdown`
- **Supported Architectures**: AMD64 (Intel/AMD) + ARM64 (Apple Silicon)
- **Image Size**: Optimized Alpine Linux base image
- **Update Frequency**: Follow project version releases
### Development Environment
If you want to participate in development or customize features:
1. **Clone Project**
```bash
git clone https://github.com/leeguooooo/markdown-site
cd markdown-site
```
2. **Install Dependencies**
```bash
# Method 1: One-click installation (recommended, automatic handling of build scripts)
pnpm run install:full
# Method 2: Standard installation
pnpm install
# If you see build script warnings (native modules), execute the following command:
pnpm approve-builds
```
3. **Start Development Server**
```bash
pnpm dev
```
4. **Access Application**
- Document Preview: http://localhost:3001
- Admin Interface: http://localhost:3001/admin (Password: admin123)
### Other Deployment Methods
#### 🐳 Local Docker Build
If you want to build your own image:
```bash
# Clone project
git clone https://github.com/leeguooooo/markdown-site
cd markdown-site
# One-click Docker deployment
pnpm docker:deploy
```
#### 🚀 Traditional Deployment
Use our secure build script, which automatically checks environment variables and deploys:
```bash
# Clone project
git clone https://github.com/leeguooooo/markdown-site
cd markdown-site
# Install dependencies (one-click installation, automatic handling of build scripts)
pnpm run install:full
# One-click secure build (automatic environment variable configuration)
pnpm build:safe
# Start PM2 service
pnpm pm2:start
```
#### 📋 Manual Deployment
If you want to manually control each step:
1. **Set Admin Password**
```bash
# Interactive password setting
pnpm security:setup
```
2. **Build Application**
```bash
# Normal build
pnpm build
# Or secure build (with environment check)
pnpm build:safe
```
3. **Start Service**
```bash
# Start with PM2 (recommended)
pnpm pm2:start
# Or start directly
pnpm start
```
#### 🔧 Deployment Management
```bash
# Check service status
pnpm pm2:status
# View logs
pnpm pm2:logs
# Restart service
pnpm pm2:restart
# Stop service
pnpm pm2:stop
```
#### 🛠️ Troubleshooting
If you encounter issues:
```bash
# Verify password setting
pnpm security:verify
# Check environment variables
node scripts/pre-build-check.js
# Clean and rebuild
pnpm clean
pnpm build:safe
```
## 📁 Project Structure
```
├── src/ # Source code directory
│ ├── app/ # Next.js App Router
│ │ ├── admin/ # Admin interface
│ │ ├── api/ # API routes
│ │ └── docs/ # Document preview page
│ ├── components/ # React components
│ │ ├── auth/ # Authentication components
│ │ ├── admin/ # Admin interface components
│ │ ├── ui/ # Basic UI components
│ │ └── docs/ # Document-related components
│ └── lib/ # Utility library
│ ├── auth.ts # Authentication logic
│ ├── logger.ts # Logging system
│ └── utils.ts # Utility functions
├── scripts/ # Core script directory (simplified)
│ ├── pre-build-check.js # Pre-build environment check
│ ├── generate-password.js # Password generation tool
│ ├── verify-password.js # Password verification tool
│ ├── safe-build.sh # Secure build script
│ ├── docker-publish.sh # Docker image publishing script
│ └── docker-entrypoint.sh # Docker container startup script
├── docs/ # Document directory
│ ├── Example Documents/ # Example and demo documents
│ ├── security/ # Security-related documents
│ └── project-docs/ # Project documentation
├── public/ # Static resources
├── .env # Environment variable configuration
├── Dockerfile # Docker image build file
├── docker-compose.yml # Docker Compose configuration
├── ecosystem.config.js # PM2 configuration file
├── SETUP.md # Detailed setup guide
└── package.json # Project configuration
```
## 🔧 Configuration Instructions
### Environment Variables
The system will automatically generate the following environment variables, no manual configuration required:
| Variable Name | Description | Default Value |
|--------|------|--------|
| `ADMIN_PASSWORD_HASH_BASE64` | Admin password hash (Base64 encoded) | Automatically generated |
| `JWT_SECRET` | JWT signature key | Automatically generated |
| `NODE_ENV` | Runtime environment | `production` |
| `PORT` | Service port | `3001` |
> 💡 **Tip**: Using Base64 encoding avoids parsing issues with special characters in environment variables
### Security Recommendations
1. **JWT Key**: Use a random string of at least 32 bits
2. **Password Policy**: Use strong passwords, change regularly
3. **HTTPS**: Use HTTPS in production environments
4. **Firewall**: Restrict access IP to the admin interface
## 📖 Usage Guide
### 🚀 Quick Experience
After one-click Docker run, you can:
1. **Access immediately**: Open http://localhost:3001
2. **Admin Dashboard**: Access http://localhost:3001/admin
3. **Default Password**: admin123 (change after first login)
### Document Management
1. **Access Admin Interface**: `/admin`
2. **Login**: Use configured admin password
3. **Upload Documents**: Drag-and-drop `.md` files to the upload area
4. **Create Documents**: Click "+" button, select template to create
5. **Edit Documents**: Click file name to enter editor
6. **Organize Structure**: Use paths to organize document hierarchy
### Document Preview
1. **Browse Documents**: Visit `/docs` to view document list
2. **Search Function**: Use top search box to quickly find
3. **Navigation**: Left tree navigation to browse document structure
### Mermaid Diagrams
Use Mermaid syntax in Markdown:
````markdown
```mermaid
graph TD
A[Start] --> B{Is there a problem?}
B -->|Yes| C[Check documentation]
B -->|No| D[Start development]
C --> E[Solve problem]
E --> D
D --> F[Complete]
```
````
## 🛠️ Development
### Tech Stack
- **Frontend**: Next.js 14, React, TypeScript, Tailwind CSS
- **Authentication**: JWT, bcryptjs
- **Markdown**: react-markdown, remark-gfm, rehype-highlight
- **Diagrams**: Mermaid
- **Search**: Fuse.js
- **Icons**: Lucide React
### Integrations
- [CI Code Review Publish API](docs/integrations/review-publish-api.md): Let GitHub Actions/Codex automatically review results land in the document library via Web API.
### Development Commands
```bash
# Development server
pnpm dev
# Build
pnpm build
# Start production server
pnpm start
# Code check
pnpm lint
# Type check
pnpm type-check
```
### Available Commands
The project provides simplified commands to manage deployment:
```bash
# 🚀 Development Commands
pnpm dev # Start development server
pnpm build # Build production version
pnpm build:safe # Secure build (with environment check)
pnpm build:docker # Docker build
pnpm start # Start production server
pnpm lint # Code check
# 🐳 Docker Deployment
pnpm docker:deploy # One-click Docker deployment
pnpm docker:build # Build Docker image
pnpm docker:compose # Start Docker Compose
pnpm docker:logs # View Docker logs
pnpm docker:stop # Stop Docker service
pnpm docker:restart # Restart Docker service
pnpm docker:manage # Docker management tool
# 📦 Docker Image Publishing
pnpm docker:publish:check # Pre-publish check
pnpm docker:publish:prepare # Publish preparation
pnpm docker:publish # Publish image to Docker Hub
# 🔐 Security Management
pnpm security:setup # Set admin password
pnpm security:verify # Verify admin password
# 🚀 PM2 Deployment
pnpm pm2:start # Start PM2 service
pnpm pm2:stop # Stop PM2 service
pnpm pm2:restart # Restart PM2 service
pnpm pm2:logs # View PM2 logs
pnpm pm2:status # View PM2 status
# 🧹 Cleanup
pnpm clean # Clean build files and logs
```
See detailed instructions in: [Setup Guide](./SETUP.md)
## 📄 License
MIT License
## 🤝 Contributing
Welcome to submit issues and pull requests!
### Contribution Guide
1. Fork project
2. Create feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to branch (`git push origin feature/AmazingFeature`)
5. Open Pull Request
## 📞 Support
### 🐳 Docker FAQs
**Q: How to customize port?**
```bash
docker run -d -p 8080:3001 --name misonote-markdown leeguo/misonote-markdown:latest
# Then access http://localhost:8080
```
**Q: How to persist data?**
```bash
# Create local directory
mkdir -p ./my-docs ./my-data
# Mount to container
docker run -d \
-p 3001:3001 \
-v $(pwd)/my-docs:/app/docs \
-v $(pwd)/my-data:/app/data \
--name misonote-markdown \
leeguo/misonote-markdown:latest
```
**Q: How to set admin password?**
```bash
# Method 1: Set at startup (recommended)
docker run -d \
-e ADMIN_PASSWORD=admin123 \
-p 3001:3001 \
--name misonote-markdown \
leeguo/misonote-markdown:latest
# Method 2: Modify after startup
docker exec -it misonote-markdown node scripts/generate-password.js
docker restart misonote-markdown
```
**Q: How to view detailed logs?**
```bash
# View application logs
docker logs -f misonote-markdown
# View container logs
docker exec misonote-markdown cat logs/app.log
```
### Other Support
If you encounter issues or have suggestions, please:
1. Check [FAQs](./docs/faq.md)
2. Submit [Issue](../../issues)
3. Check [Documentation](./docs)
4. Visit [Docker Hub](https://hub.docker.com/r/leeguo/misonote-markdown)
---
## 👨💻 Author
**leeguoo** - [GitHub](https://github.com/leeguooooo) | [Personal Homepage](docs/关于作者/leeguoo.md)
## 🌟 Acknowledgements
Thanks to all contributors who have contributed to this project!
**Enjoy using Markdown document system!**
