130 lines
4.5 KiB
Markdown
130 lines
4.5 KiB
Markdown
# MarkdownHub
|
|
|
|
Self-hosted collaborative markdown workspace with real-time editing, Git integration, and AI-powered code generation.
|
|
|
|
## Features
|
|
|
|
- **Three editor modes**: WYSIWYG (Milkdown), raw markdown (CodeMirror-style), and split-pane with live preview
|
|
- **File management**: Tree-based file browser, folders, search, create/delete
|
|
- **Git versioning**: Auto-commit on save, full history, diff viewer, restore previous versions
|
|
- **External Git sync**: Per-user remotes (Gitea, GitHub, etc.), push/pull on demand
|
|
- **Sharing**: Share files/folders with other users (read-only or read-write)
|
|
- **AI integration**: Verify specs, generate prompts, summarize — via LiteLLM/vLLM
|
|
- **AI Build Pipeline**: Write a spec → verify → build entire project → push to Gitea
|
|
- **2FA**: TOTP-based two-factor authentication
|
|
- **Light/Dark theme**: Toggle in UI, persisted in preferences
|
|
- **Export**: PDF, HTML, raw markdown download
|
|
- **Offline-ready**: PWA architecture (planned)
|
|
- **Multi-device**: Responsive, works on desktop and iPad
|
|
- **Docker deployment**: Single container, easy backup
|
|
|
|
## Quick Start
|
|
|
|
### Docker (recommended)
|
|
|
|
```bash
|
|
docker build -t markdownhub .
|
|
docker run -d --name markdownhub \
|
|
-p 8080:8080 \
|
|
-v ./data:/app/data \
|
|
-e MH_SECRET=your-random-secret \
|
|
markdownhub
|
|
```
|
|
|
|
Default admin: `admin@localhost` / `admin`
|
|
|
|
### Development
|
|
|
|
**Backend:**
|
|
```bash
|
|
go run ./cmd/server
|
|
```
|
|
|
|
**Frontend:**
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
Frontend dev server proxies API calls to `localhost:8080`.
|
|
|
|
## Configuration
|
|
|
|
Environment variables:
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `MH_PORT` | `8080` | Server port |
|
|
| `MH_DATA_DIR` | `./data` | Data directory (SQLite + files) |
|
|
| `MH_SECRET` | `dev-secret-change-me` | JWT signing secret |
|
|
| `MH_ADMIN_EMAIL` | `admin@localhost` | Initial admin email |
|
|
| `MH_ADMIN_PASSWORD` | `admin` | Initial admin password |
|
|
| `MH_AI_ENDPOINT` | — | LiteLLM-compatible API URL |
|
|
| `MH_AI_API_KEY` | — | API key for AI endpoint |
|
|
| `MH_AI_MODEL` | `gpt-4` | Default model for AI features |
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────┐ ┌──────────────┐ ┌────────┐
|
|
│ Frontend │────▶│ Go Backend │────▶│ SQLite │
|
|
│ (Vue 3) │◀────│ (net/http) │ └────────┘
|
|
└─────────────┘ │ │────▶ Filesystem (.md files)
|
|
│ │────▶ Git (per-user repos)
|
|
└──────────────┘
|
|
│
|
|
┌──────▼───────┐ ┌────────┐
|
|
│ Build Daemon │────▶│ Gitea │
|
|
│ (Python) │ └────────┘
|
|
└──────────────┘
|
|
```
|
|
|
|
- **Backend**: Go, stdlib `net/http`, SQLite (pure Go via modernc.org/sqlite)
|
|
- **Frontend**: Vue 3, Vite, Milkdown, CodeMirror 6, marked
|
|
- **Auth**: JWT + bcrypt + TOTP
|
|
- **Git**: Shell-based git operations (auto-commit, remotes, push/pull)
|
|
- **AI**: LiteLLM-compatible OpenAI API calls
|
|
- **Build Daemon**: Python (stdlib only), polls for build jobs, runs Pi coding agent
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
cmd/server/ — Web server entry point
|
|
cmd/mdsync/ — CLI sync tool (planned)
|
|
internal/api/ — HTTP handlers & routing
|
|
internal/auth/ — JWT, bcrypt, TOTP
|
|
internal/db/ — SQLite schema & connection
|
|
internal/files/ — File CRUD & search
|
|
internal/git/ — Git operations
|
|
internal/crypto/ — AES-256-GCM encryption (for private vault)
|
|
daemon/ — Build daemon (Python)
|
|
frontend/ — Vue 3 SPA
|
|
```
|
|
|
|
## Build Daemon
|
|
|
|
The build daemon runs on a separate Linux machine and processes AI build jobs:
|
|
|
|
```bash
|
|
export MH_URL=http://your-markdownhub:8080
|
|
export MH_DAEMON_TOKEN=your-token
|
|
export MH_WORKSPACE=~/builds
|
|
python3 daemon/build_daemon.py
|
|
```
|
|
|
|
It polls MarkdownHub for pending jobs, creates Gitea repos, runs the Pi coding agent, and pushes results.
|
|
|
|
## Backup & Restore
|
|
|
|
All data lives in the `data/` volume:
|
|
- `data/db/markdownhub.db` — SQLite database
|
|
- `data/files/{user_id}/` — User markdown files (also git repos)
|
|
|
|
**Backup**: Copy the `data/` directory.
|
|
**Restore**: Stop container, replace `data/`, start container.
|
|
|
|
## License
|
|
|
|
MIT
|