From fe71b01f2d3c1bbbb365daba3d7968ba5dbe4367 Mon Sep 17 00:00:00 2001 From: Steven Date: Wed, 4 Jun 2025 23:10:31 +0800 Subject: [PATCH] chore: polish readme --- README.md | 242 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 205 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 453024fce..b8724ccdf 100644 --- a/README.md +++ b/README.md @@ -1,59 +1,227 @@ -# Memos - Open Source, Self-hosted, Your Notes, Your Way +# Memos Memos -An open-source, self-hosted note-taking solution designed for seamless deployment and multi-platform access. Experience effortless plain text writing with pain-free, complemented by robust Markdown syntax support for enhanced formatting. +A modern, open-source, self-hosted knowledge management and note-taking platform designed for privacy-conscious users and organizations. Memos provides a lightweight yet powerful solution for capturing, organizing, and sharing thoughts with comprehensive Markdown support and cross-platform accessibility. -Home Page • -Blogs • -Docs • -Live Demo +
-

- Ask DeepWiki - Docker pull - Docker image size - Discord -

+[![Home Page](https://img.shields.io/badge/Home-www.usememos.com-blue)](https://www.usememos.com) +[![Documentation](https://img.shields.io/badge/Docs-Available-green)](https://www.usememos.com/docs) +[![Live Demo](https://img.shields.io/badge/Demo-Try%20Now-orange)](https://demo.usememos.com/) +[![Blog](https://img.shields.io/badge/Blog-Read%20More-lightblue)](https://www.usememos.com/blog) -![demo](https://www.usememos.com/demo.png) +[![Docker Pulls](https://img.shields.io/docker/pulls/neosmemo/memos.svg)](https://hub.docker.com/r/neosmemo/memos) +[![Docker Image Size](https://img.shields.io/docker/image-size/neosmemo/memos?sort=semver)](https://hub.docker.com/r/neosmemo/memos) +[![Discord](https://img.shields.io/badge/discord-chat-5865f2?logo=discord&logoColor=f5f5f5)](https://discord.gg/tfPJa4UmAv) -## Features +
-- **Privacy First** 🏡: Your data, your control. All runtime data is securely stored in your local database. -- **Create at Speed** ✍️: Write and save content as plain text for quick access, with Markdown support for fast formatting and easy sharing. -- **Lightweight but Powerful** ⚡: Built with Go and React.js, our app combines a compact architecture with powerful performance. -- **Customizable** 🧩: Personalize your experience by customizing the server name, icon, description, theme, and execution scripts. -- **Open Source** 🦦: Fully open source, with all code available on GitHub for transparency and collaboration. -- **Free to Use** 💸: Enjoy all features at no cost, no hidden fees, no subscriptions. +![Memos Application Screenshot](https://www.usememos.com/demo.png) -## Deploy with Docker in seconds +## Table of Contents + +- [Overview](#overview) +- [Key Features](#key-features) +- [Quick Start](#quick-start) +- [Installation Methods](#installation-methods) +- [Development Setup](#development-setup) +- [Contributing](#contributing) +- [License](#license) + +## Overview + +Memos is a lightweight, self-hosted alternative to cloud-based note-taking services. Built with privacy and performance in mind, it offers a comprehensive platform for personal knowledge management without compromising data ownership or security. + +## Key Features + +### Data Privacy and Security + +- **Complete Data Ownership**: All application data is stored locally in your chosen database +- **Self-Hosted Architecture**: Full control over your data infrastructure and access policies +- **No External Dependencies**: Runtime operations require no third-party services or cloud connections + +### Content Creation and Management + +- **Plain Text Efficiency**: Streamlined text input with immediate save functionality +- **Advanced Markdown Support**: Comprehensive Markdown rendering with syntax highlighting +- **Rich Media Integration**: Support for images, links, and embedded content +- **Real-time Collaboration**: Multi-user support with concurrent editing capabilities + +### Technical Excellence + +- **High-Performance Backend**: Built with Go for optimal resource utilization and scalability +- **Modern Frontend**: React.js-based user interface with responsive design +- **Lightweight Deployment**: Minimal system requirements with efficient resource consumption +- **Cross-Platform Compatibility**: Supports Linux, macOS, Windows, and containerized environments + +### Customization and Extensibility + +- **Configurable Interface**: Customizable server branding, themes, and user interface elements +- **API-First Design**: RESTful API with comprehensive documentation for third-party integrations +- **Plugin Architecture**: Extensible system for custom functionality and integrations +- **Multi-Database Support**: Compatible with SQLite, PostgreSQL, and MySQL databases + +### Cost-Effective Solution + +- **Open Source License**: MIT licensed with full source code availability +- **Zero Licensing Costs**: No subscription fees, usage limits, or premium tiers +- **Community-Driven Development**: Active community contribution and transparent development process + +## Quick Start + +### Prerequisites + +- Docker and Docker Compose installed on your system +- Minimum 512MB RAM and 1GB available disk space + +### Docker Deployment + +Deploy Memos in production mode using Docker: ```bash -docker run -d --name memos -p 5230:5230 -v ~/.memos/:/var/opt/memos neosmemo/memos:stable +# Create data directory +mkdir -p ~/.memos + +# Run Memos container +docker run -d \ + --name memos \ + --restart unless-stopped \ + -p 5230:5230 \ + -v ~/.memos:/var/opt/memos \ + neosmemo/memos:stable ``` -> [!NOTE] -> This command is only applicable for Unix/Linux systems. For Windows, please refer to the detailed [documentation](https://www.usememos.com/docs/install/container-install#docker-on-windows). +Access the application at `http://localhost:5230` and complete the initial setup process. + +### Docker Compose Deployment + +For advanced configurations, use Docker Compose: + +```yaml +# docker-compose.yml +version: "3.8" +services: + memos: + image: neosmemo/memos:stable + container_name: memos + restart: unless-stopped + ports: + - "5230:5230" + volumes: + - ./data:/var/opt/memos + environment: + - MEMOS_MODE=prod + - MEMOS_PORT=5230 +``` + +Deploy with: + +```bash +docker-compose up -d +``` + +> **Note**: The data directory (`~/.memos/` or `./data/`) stores all application data including the database, uploaded files, and configuration. Ensure this directory is included in your backup strategy. > -> The `~/.memos/` directory will be used as the data directory on your local machine, while `/var/opt/memos` is the directory of the volume in Docker and should not be modified. +> **Platform Compatibility**: The above commands are optimized for Unix-like systems (Linux, macOS). For Windows deployments, please refer to the [Windows-specific documentation](https://www.usememos.com/docs/install/container-install#docker-on-windows). -Learn more about [other installation methods](https://www.usememos.com/docs/install). +## Installation Methods -> [!WARNING] -> Memos is still under active development, so you may encounter bugs or breaking changes as we improve. +Memos supports multiple installation approaches to accommodate different deployment scenarios: -## Contribution +### Container Deployment -Contributions are what make the open-source community such an amazing place to learn, inspire, and create. We greatly appreciate any contributions you make. Thank you for being a part of our community! 🥰 +- **Docker Hub**: Official images available at `neosmemo/memos` +- **GitHub Container Registry**: Alternative registry with the same image versions +- **Kubernetes**: Helm charts and YAML manifests for cluster deployments -Guide to [contribution](https://www.usememos.com/docs/contribution/development). +### Binary Installation -## Star history +- **Pre-compiled Binaries**: Available for Linux, macOS, and Windows on the releases page +- **Package Managers**: Distribution-specific packages for major Linux distributions +- **Homebrew**: macOS installation via `brew install memos` + +### Source Installation + +- **Go Build**: Compile from source using Go 1.24 or later +- **Development Mode**: Local development setup with hot reloading + +For detailed installation instructions, refer to the [comprehensive installation guide](https://www.usememos.com/docs/install). + +## Development Setup + +### Prerequisites + +- Go 1.24 or later +- Node.js 22+ and pnpm +- Git for version control + +### Backend Development + +```bash +# Clone the repository +git clone https://github.com/usememos/memos.git +cd memos + +# Install Go dependencies +go mod download + +# Run the backend server +go run ./bin/memos/main.go --mode dev --port 8081 +``` + +### Frontend Development + +```bash +# Navigate to web directory +cd web + +# Install dependencies +pnpm install + +# Start development server +pnpm dev +``` + +The development servers will be available at: + +- Backend API: `http://localhost:8081` +- Frontend: `http://localhost:3001` + +## Contributing + +Memos is an open-source project that welcomes contributions from developers, designers, and users worldwide. We maintain a collaborative and inclusive development environment that values quality, innovation, and community feedback. + +### Ways to Contribute + +- **Code Contributions**: Bug fixes, feature implementations, and performance improvements +- **Documentation**: API documentation, user guides, and technical specifications +- **Testing**: Quality assurance, test case development, and bug reporting +- **Localization**: Translation support for multiple languages and regions +- **Community Support**: Helping users on Discord, GitHub discussions, and forums + +## License + +Memos is released under the MIT License, providing maximum flexibility for both personal and commercial use. This license allows for: + +- **Commercial Use**: Deploy Memos in commercial environments without licensing fees +- **Modification**: Adapt and customize the codebase for specific requirements +- **Distribution**: Share modified versions while maintaining license attribution +- **Private Use**: Use Memos internally without disclosure requirements + +See the [LICENSE](./LICENSE) file for complete licensing terms. + +## Project Status + +> **Development Status**: Memos is actively maintained and under continuous development. While the core functionality is stable and production-ready, users should expect regular updates, feature additions, and potential breaking changes as the project evolves. +> +> **Version Compatibility**: We maintain backward compatibility for data storage and API interfaces where possible. Migration guides are provided for major version transitions. + +## Support and Community + +- **Documentation**: [Official Documentation](https://www.usememos.com/docs) +- **Community Chat**: [Discord Server](https://discord.gg/tfPJa4UmAv) +- **Issue Tracking**: [GitHub Issues](https://github.com/usememos/memos/issues) +- **Discussions**: [GitHub Discussions](https://github.com/usememos/memos/discussions) [![Star History Chart](https://api.star-history.com/svg?repos=usememos/memos&type=Date)](https://star-history.com/#usememos/memos&Date) - -## Other Projects - -- [**Slash**](https://github.com/yourselfhosted/slash): An open source, self-hosted bookmarks and link sharing platform. Save and share your links very easily. -- [**Gomark**](https://github.com/usememos/gomark): A markdown parser written in Go for Memos. And its [WebAssembly version](https://github.com/usememos/gomark-wasm) is also available.