{"id":32808745,"url":"https://github.com/gamosoft/notediscovery","last_synced_at":"2026-04-02T12:01:55.326Z","repository":{"id":322796515,"uuid":"1090271647","full_name":"gamosoft/NoteDiscovery","owner":"gamosoft","description":"Your Self-Hosted Knowledge Base","archived":false,"fork":false,"pushed_at":"2026-02-09T17:17:32.000Z","size":4698,"stargazers_count":2197,"open_issues_count":1,"forks_count":184,"subscribers_count":10,"default_branch":"main","last_synced_at":"2026-02-09T20:55:59.234Z","etag":null,"topics":["alternative","docker","evernote","fastapi","free","hosted","knowledge-base","markdown","note","note-taking","notion","obsidian","onenote","open-source","privacy","python","second-brain","self-hosted","zettelkasten"],"latest_commit_sha":null,"homepage":"https://www.notediscovery.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gamosoft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"ko_fi":"gamosoft","custom":["https://paypal.me/gamosoft"]}},"created_at":"2025-11-05T12:54:29.000Z","updated_at":"2026-02-09T17:17:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gamosoft/NoteDiscovery","commit_stats":null,"previous_names":["gamosoft/notediscovery"],"tags_count":47,"template":false,"template_full_name":null,"purl":"pkg:github/gamosoft/NoteDiscovery","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gamosoft%2FNoteDiscovery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gamosoft%2FNoteDiscovery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gamosoft%2FNoteDiscovery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gamosoft%2FNoteDiscovery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gamosoft","download_url":"https://codeload.github.com/gamosoft/NoteDiscovery/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gamosoft%2FNoteDiscovery/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29298525,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-10T10:40:02.018Z","status":"ssl_error","status_checked_at":"2026-02-10T10:38:28.459Z","response_time":65,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alternative","docker","evernote","fastapi","free","hosted","knowledge-base","markdown","note","note-taking","notion","obsidian","onenote","open-source","privacy","python","second-brain","self-hosted","zettelkasten"],"created_at":"2025-11-06T19:01:09.582Z","updated_at":"2026-04-02T12:01:55.319Z","avatar_url":"https://github.com/gamosoft.png","language":"JavaScript","readme":"# 📝 NoteDiscovery\n\n![GitHub Stars](https://img.shields.io/github/stars/gamosoft/notediscovery?style=flat)\n![Build](https://img.shields.io/github/actions/workflow/status/gamosoft/notediscovery/docker-publish.yml)\n![Latest Version](https://img.shields.io/github/v/tag/gamosoft/notediscovery)\n![License](https://img.shields.io/github/license/gamosoft/notediscovery)\n\n\n\n\u003e Your Self-Hosted Knowledge Base\n\n## What is NoteDiscovery?\n\nNoteDiscovery is a **lightweight, self-hosted note-taking application** that puts you in complete control of your knowledge base. Write, organize, and discover your notes with a beautiful, modern interface—all running on your own server.\n\n![Note Discovery](docs/carousel-1.jpg)\n\n## 🎯 Who is it for?\n\n- **Privacy-conscious users** who want complete control over their data\n- **Developers** who prefer markdown and local file storage\n- **Knowledge workers** building a personal wiki or second brain\n- **Teams** looking for a self-hosted alternative to commercial apps\n- **Anyone** who values simplicity, speed, and ownership\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.notediscovery.com\"\u003e\u003cimg src=\"docs/website-button.svg\" alt=\"Official Website\"\u003e\u003c/a\u003e\n  \u0026nbsp;\u0026nbsp;\n  \u003ca href=\"https://gamosoft-notediscovery-demo.hf.space\"\u003e\u003cimg src=\"docs/demo-button.svg\" alt=\"Try Live Demo\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.pikapods.com/pods?run=notediscovery\"\u003e\u003cimg src=\"https://www.pikapods.com/static/run-button.svg\" alt=\"Run on PikaPods\"\u003e\u003c/a\u003e\n  \u0026nbsp;\u0026nbsp;\n  \u003ca href=\"https://ko-fi.com/gamosoft\"\u003e\u003cimg src=\"https://ko-fi.com/img/githubbutton_sm.svg\" alt=\"Buy Me a Coffee at ko-fi.com\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## ✨ Why NoteDiscovery?\n\n### vs. Commercial Apps (Notion, Evernote, Obsidian Sync)\n\n| Feature | NoteDiscovery | Commercial Apps |\n|---------|---------------|-----------------|\n| **Cost** | 100% Free | $xxx/month/year |\n| **Privacy** | Your server, your data | Their servers, their terms |\n| **Speed** | Lightning fast | Depends on internet |\n| **Offline** | Always works | Limited or requires sync |\n| **Customization** | Full control | Limited options |\n| **No Lock-in** | Plain markdown files | Proprietary formats |\n\n### Key Benefits\n\n- 🔒 **Total Privacy** - Your notes never leave your server\n- 🔐 **Optional Authentication** - Simple password protection for self-hosted deployments\n- 💰 **Zero Cost** - No subscriptions, no hidden fees\n- 🚀 **Fast \u0026 Lightweight** - Instant search and navigation\n- 🎨 **Beautiful Themes** - Multiple themes, easy to customize\n- 🔌 **Extensible** - Plugin system for custom features\n- 📱 **Responsive** - Works on desktop, tablet, and mobile\n- 📂 **Simple Storage** - Plain markdown files in folders\n- 🧮 **Math Support** - LaTeX/MathJax for beautiful equations\n- 📄 **HTML Export** - Share notes as standalone HTML files\n- 🕸️ **Graph View** - Interactive visualization of connected notes\n- ⭐ **Favorites** - Star your most-used notes for instant access\n- 📑 **Outline Panel** - Navigate headings with click-to-jump TOC\n- 🤖 **AI Assistant Ready** - MCP integration for Claude, Cursor \u0026 more\n\n## 🤖 AI-Powered Note Management\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/MCP-Compatible-blueviolet?style=for-the-badge\u0026logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IndoaXRlIiBzdHJva2Utd2lkdGg9IjIiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgc3Ryb2tlLWxpbmVqb2luPSJyb3VuZCI+PHBhdGggZD0iTTEyIDJhMTAgMTAgMCAxIDAgMTAgMTBIMTJWMnoiLz48cGF0aCBkPSJNMjEuMTggOC44MmMtLjI4LS40LS43Mi0uODItMS4xOC0uODJoLTNjLS40NiAwLS45LjQyLTEuMTguODItLjI4LjQtLjMyLjk4LS4xMiAxLjQybDEuNSAzYy4yLjQ0LjY2LjcgMS4xMi43aDEuMzZjLjQ2IDAgLjkyLS4yNiAxLjEyLS43bDEuNS0zYy4yLS40NC4xNi0xLjAyLS4xMi0xLjQyeiIvPjwvc3ZnPg==\" alt=\"MCP Compatible\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Works%20with-Claude-orange?style=for-the-badge\" alt=\"Works with Claude\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Works%20with-Cursor-blue?style=for-the-badge\" alt=\"Works with Cursor\"\u003e\n\u003c/p\u003e\n\nNoteDiscovery includes a built-in **Model Context Protocol (MCP)** server, letting AI assistants directly interact with your notes:\n\n| What AI Can Do | Example |\n|----------------|---------|\n| 🔍 **Search \u0026 Discover** | *\"Find all my notes about Docker deployment\"* |\n| 📝 **Create \u0026 Edit** | *\"Create a meeting notes template for tomorrow\"* |\n| 📁 **Organize** | *\"Move all project notes to the archive folder\"* |\n| 🏷️ **Tag \u0026 Categorize** | *\"List all notes tagged with #urgent\"* |\n| 📊 **Explore Connections** | *\"Show me the knowledge graph of my notes\"* |\n| ✍️ **Append Ideas** | *\"Add this thought to my daily journal\"* |\n\n**One-line setup** for Cursor, Claude Desktop, and other MCP-compatible tools:\n\n```json\n{\n  \"mcpServers\": {\n    \"notediscovery\": {\n      \"command\": \"docker\",\n      \"args\": [\"run\", \"--rm\", \"-i\", \"-e\", \"NOTEDISCOVERY_URL=http://host.docker.internal:8000\", \"ghcr.io/gamosoft/notediscovery:latest\", \"python\", \"-m\", \"mcp_server\"]\n    }\n  }\n}\n```\n\n\u003e 💡 **See [MCP.md](documentation/MCP.md)** for complete setup instructions and all available tools.\n\n## 🚀 Quick Start\n\n### Quick Setup\n\n**Linux/macOS:**\n```bash\nmkdir -p notediscovery/data \u0026\u0026 cd notediscovery\ndocker run -d --name notediscovery -p 8000:8000 \\\n  -v $(pwd)/data:/app/data \\\n  ghcr.io/gamosoft/notediscovery:latest\n```\n\n**Windows (PowerShell):**\n```powershell\nmkdir notediscovery\\data; cd notediscovery\ndocker run -d --name notediscovery -p 8000:8000 `\n  -v ${PWD}/data:/app/data `\n  ghcr.io/gamosoft/notediscovery:latest\n```\n\nOpen **http://localhost:8000** — done! 🎉  \n\n\n\u003e 💡 Your notes are saved in `./data/`. Themes, plugins, locales and default configuration values are included in the image.\n\n### Using Docker Compose\n\nTwo docker-compose files are provided:\n\n| File | Use Case |\n|------|----------|\n| `docker-compose.ghcr.yml` | **Recommended** - Uses pre-built image from GitHub Container Registry |\n| `docker-compose.yml` | For development - Builds from local source |\n\n**Option 1: Pre-built image (fastest)**\n\nLinux/macOS:\n```bash\nmkdir -p notediscovery/data \u0026\u0026 cd notediscovery\ncurl -O https://raw.githubusercontent.com/gamosoft/notediscovery/main/docker-compose.ghcr.yml\ndocker-compose -f docker-compose.ghcr.yml up -d\n```\n\nWindows (PowerShell):\n```powershell\nmkdir notediscovery\\data; cd notediscovery\nInvoke-WebRequest -Uri https://raw.githubusercontent.com/gamosoft/notediscovery/main/docker-compose.ghcr.yml -OutFile docker-compose.ghcr.yml\ndocker-compose -f docker-compose.ghcr.yml up -d\n```\n\n**Option 2: Build from source (for development)**\n```bash\ngit clone https://github.com/gamosoft/notediscovery.git\ncd notediscovery\ndocker-compose up -d\n```\n\nSee [Advanced Docker Setup](#advanced-docker-setup) for volume details.\n\n\n### Running Locally (Without Docker)\n\nFor development or if you prefer running directly:\n\n```bash\n# Clone the repository\ngit clone https://github.com/gamosoft/notediscovery.git\ncd notediscovery\n\n# Install dependencies\npip install -r requirements.txt\n\n# Run the application\npython run.py\n\n# Access at http://localhost:8000\n```\n\n**Requirements:**\n- Python 3.8 or higher\n- pip (Python package manager)\n\n#### Using Virtual Environments (Recommended for Arch/Fedora/Ubuntu 23.04+)\n\nModern Linux distributions enforce [PEP 668](https://peps.python.org/pep-0668/), which prevents system-wide pip installs. Use a virtual environment instead:\n\n```bash\n# Clone the repository\ngit clone https://github.com/gamosoft/notediscovery.git\ncd notediscovery\n\n# Create a virtual environment\npython -m venv venv\n\n# Activate it (choose your shell):\nsource venv/bin/activate        # Bash/Zsh (most Linux distros)\nsource venv/bin/activate.fish   # Fish (CachyOS, etc.)\nsource venv/bin/activate.csh    # Csh/Tcsh\n.\\venv\\Scripts\\activate         # Windows PowerShell\n\n# Install dependencies and run\npip install -r requirements.txt\npython run.py\n```\n\n\u003e ⚠️ **Warning**\n\u003e\n\u003e *You'll need to activate the virtual environment (source venv/bin/activate) each time you open a new terminal before running the app*\n\n### Advanced Docker Setup\n\nThe image includes bundled config, themes, plugins, and locales. To customize, you must:\n1. **Map the volume** in your docker-compose or docker run command\n2. **Provide content** - the file/folder must exist with valid content (empty = app might break!)\n\n| Volume | Purpose | Bundled? |\n|--------|---------|----------|\n| `data/` | Your notes | ❌ You must create |\n| `config.yaml` | App settings | ✅ Yes |\n| `themes/` | Custom themes | ✅ Yes |\n| `plugins/` | Custom plugins | ✅ Yes |\n| `locales/` | Translations | ✅ Yes |\n\n### Dashboard Integration\n\n\u003ca href=\"https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/notediscovery.svg\" target=\"_blank\"\u003e\n  \u003cimg src=\"https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/notediscovery.svg\" alt=\"NoteDiscovery Icon\" width=\"64\" height=\"64\"\u003e\n\u003c/a\u003e\n\nAn official icon for NoteDiscovery is now available on [Dashboard Icons](https://dashboardicons.com/icons/notediscovery)!  \nUse it in your self-hosted dashboards like Homepage, Homarr, Dashy, Heimdall, etc...\n\n## 📚 Documentation\n\nWant to learn more?\n\n- 🎨 **[THEMES.md](documentation/THEMES.md)** - Theme customization and creating custom themes\n- ✨ **[FEATURES.md](documentation/FEATURES.md)** - Complete feature list and keyboard shortcuts\n- 🏷️ **[TAGS.md](documentation/TAGS.md)** - Organize notes with tags and combined filtering\n- 📋 **[TEMPLATES.md](documentation/TEMPLATES.md)** - Create notes from reusable templates with dynamic placeholders\n- 🧮 **[MATHJAX.md](documentation/MATHJAX.md)** - LaTeX/Math notation examples and syntax reference\n- 📊 **[MERMAID.md](documentation/MERMAID.md)** - Diagram creation with Mermaid (flowcharts, sequence diagrams, and more)\n- 🔌 **[PLUGINS.md](documentation/PLUGINS.md)** - Plugin system and available plugins\n- 🌐 **[API.md](documentation/API.md)** - REST API documentation and examples\n- 🤖 **[MCP.md](documentation/MCP.md)** - AI assistant integration (Claude, Cursor, and more)\n- 🔐 **[AUTHENTICATION.md](documentation/AUTHENTICATION.md)** - Enable password protection for your instance\n- 🔧 **[ENVIRONMENT_VARIABLES.md](documentation/ENVIRONMENT_VARIABLES.md)** - Configure settings via environment variables\n\n## 🌍 Multiple Languages\n\nNoteDiscovery supports multiple languages! Currently available:\n- 🇺🇸 English (en-US) - Default\n- 🇪🇸 Español (es-ES)\n- 🇩🇪 Deutsch (de-DE)\n- 🇫🇷 Français (fr-FR)\n\n**To change language:** Go to Settings (gear icon) → Language dropdown.\n\n**To add your own language:** See the [Contributing Guidelines](CONTRIBUTING.md#-contributing-translations) for instructions on creating translation files.\n\n**Docker users:** Mount your custom locales folder to add or override translations:\n\n```yaml\nvolumes:\n  - ./locales:/app/locales  # Custom translations\n```\n\n💡 **Pro Tip:** If you clone this repository, you can mount the `documentation/` folder to view these docs inside the app:\n\n```yaml\n# In your docker-compose.yml\nvolumes:\n  - ./data:/app/data              # Your personal notes\n  - ./documentation:/app/data/docs:ro  # Mount docs subfolder inside the data folder (read-only)\n```\n\nThen access them at `http://localhost:8000` - the docs will appear as a `docs/` folder in the file browser!\n\n## 🤝 Contributing\n\n**Before submitting a pull request**, especially for major changes, please:\n- Read our **[Contributing Guidelines](CONTRIBUTING.md)**\n- Open an issue first to discuss major features or significant changes\n- Ensure your code follows the project's style and philosophy\n\n\n## 🔒 Security Considerations\n\nNoteDiscovery is designed for **self-hosted, private use**. Please keep these security considerations in mind:\n\n### Network Security\n- ⚠️ **Do NOT expose directly to the internet** without additional security measures\n- Run behind a reverse proxy (nginx, Caddy) with HTTPS for production use\n- Keep it on your local network or use a VPN for remote access\n- By default, the app listens on `0.0.0.0:8000` (all network interfaces)\n\n### Authentication\n- **Password protection is DISABLED by default** (default password: `admin`)\n- ⚠️ **ENABLE AUTHENTICATION AND CHANGE THE DEFAULT PASSWORD** if exposing to a network!\n- See **[AUTHENTICATION.md](documentation/AUTHENTICATION.md)** for complete setup instructions\n- To disable auth, set `authentication.enabled: false` in `config.yaml`\n- Perfect for single-user or small team deployments\n- For multi-user setups, consider a reverse proxy with OAuth/SSO\n\n### Data Privacy\n- Your notes are stored as **plain text markdown files** in the `data/` folder\n- No data is sent to external services\n- Regular backups are recommended\n\n### Best Practices\n- Run on `localhost` or a private network only\n- Use Docker for isolation and easier security management\n- Keep your system and dependencies updated\n- Review and audit any plugins you install\n- Set appropriate file permissions on the `data/` directory\n\n**TL;DR**: Perfect for personal use on your local machine or home network. Enable built-in password protection if needed, or use a reverse proxy with authentication if exposing to wider networks.\n\n## 📄 License\n\nMIT License - Free to use, modify, and distribute.\n\n---\n\nMade with ❤️ for the self-hosting community\n","funding_links":["https://ko-fi.com/gamosoft","https://paypal.me/gamosoft"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgamosoft%2Fnotediscovery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgamosoft%2Fnotediscovery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgamosoft%2Fnotediscovery/lists"}