usaa.ma
A deployable markdown editor that connects with your self hosted files and lets you edit in a beautiful interface
1# MarkEdit
2
3A modern, git-based markdown editor for managing blog posts stored in GitHub repositories. Edit your markdown files with a beautiful WYSIWYG editor, track changes with automatic version control, and publish updates via pull requests.
4
5## Features
6
7- **Beautiful WYSIWYG Editor** - Rich text editing powered by TipTap with markdown support
8- **Frontmatter Support** - Edit YAML frontmatter metadata alongside your content
9- **Auto-save** - Changes are automatically saved as drafts every 2 seconds
10- **Git Integration** - Automatic branching, commits, and pull request creation
11- **GitHub OAuth** - Secure authentication with your GitHub account
12- **Multi-repo Support** - Work with multiple repositories and folder structures
13- **Fast & Lightweight** - Built with modern technologies for optimal performance
14- **Docker Ready** - Easy deployment with Docker and docker-compose
15
16## Quick Start
17
18### Prerequisites
19
20- Docker and Docker Compose installed
21- GitHub OAuth application credentials ([Setup Guide](./SETUP.md))
22
23### Run with Docker
24
251. Clone the repository:
26
27```bash
28git clone https://tangled.org/usaa.ma/markedit
29cd markedit
30```
31
322. Copy the environment file and configure:
33
34```bash
35cp .env.example .env
36# Edit .env with your GitHub OAuth credentials
37```
38
393. Start the application:
40
41```bash
42make up
43```
44
454. Open your browser to `http://localhost:3000`
46
47That's it! The application will be running with all dependencies containerized.
48
49## Development
50
51### Local Development Setup
52
53#### Backend
54
55Requirements:
56
57- Go 1.24 or higher
58
59```bash
60cd backend
61cp .env.example .env
62# Edit .env with your credentials
63
64# Run migrations and start server
65go run cmd/server/main.go
66```
67
68The backend will start on `http://localhost:8080`
69
70#### Frontend
71
72Requirements:
73
74- Bun 1.x or higher
75
76```bash
77cd frontend
78bun install
79bun run dev
80```
81
82The frontend will start on `http://localhost:4321`
83
84## How It Works
85
86### Workflow
87
881. **Authenticate** - Sign in with your GitHub account
892. **Select Repository** - Choose the GitHub repo containing your blog posts
903. **Select Folder** - Optionally specify a folder within the repo
914. **Edit Files** - Browse and edit markdown files with the WYSIWYG editor
925. **Auto-save** - Changes are automatically saved as drafts
936. **Publish** - Create a pull request with your changes
94
95### Git Integration
96
97MarkEdit uses a smart branching strategy:
98
99- Creates timestamped branches: `markedit-{unix_timestamp}`
100- Reuses branches if they're less than 4 hours old
101- Automatically commits your changes with descriptive messages
102- Creates pull requests with your custom title and description
103- Cleans up drafts after successful publication
104
105### Draft System
106
107- All edits are saved as drafts in the SQLite database
108- Drafts are user-specific and file-specific
109- Published changes replace the draft content
110- Drafts are automatically deleted after successful PR creation
111
112## Configuration
113
114### Environment Variables
115
116See [SETUP.md](./SETUP.md) for detailed configuration instructions.
117
118**Backend** (`.env`):
119
120```bash
121GITHUB_CLIENT_ID=your_github_oauth_client_id
122GITHUB_CLIENT_SECRET=your_github_oauth_client_secret
123SESSION_SECRET=random-32-character-string
124DATABASE_PATH=./data/markedit.db
125GIT_CACHE_DIR=./data/repos
126CORS_ALLOWED_ORIGINS=http://localhost:4321,http://localhost:3000
127```
128
129**Frontend** (`frontend/.env`):
130
131```bash
132PUBLIC_API_URL=http://localhost:8080
133```
134
135## Deployment
136
137### Docker Production Deployment
138
1391. Configure environment variables in `.env`
1402. Build and start containers:
141
142```bash
143make build
144make up
145```
146
1473. Check logs:
148
149```bash
150make logs
151```
152
1534. Stop containers:
154
155```bash
156make down
157```
158
159### Manual Deployment
160
161See [SETUP.md](./SETUP.md) for detailed deployment instructions for various platforms.
162
163## Makefile Commands
164
165```bash
166make build # Build Docker images
167make up # Start containers
168make down # Stop containers
169make restart # Restart containers
170make logs # View logs
171make logs-f # Follow logs
172make clean # Remove containers and volumes
173make shell-be # Access backend shell
174make shell-fe # Access frontend shell
175```
176
177## Security
178
179- OAuth tokens are securely stored and never exposed to the frontend
180- Session cookies are encrypted and HTTP-only
181- File operations are scoped to authenticated user's accessible repos
182- Git operations use the user's GitHub token with appropriate permissions
183
184## Contributing
185
186I am not expecting contributions yet. I will have a guide here once I am ready.
187
188## License
189
190MIT License - see [LICENSE](./LICENSE) for details
191
192## Support
193
194For detailed setup instructions, see [SETUP.md](./SETUP.md)
195
196For issues and feature requests, please use [Tangled Issues](https://tangled.org/usaa.ma/markedit/issues)