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## Tech Stack
17
18### Backend
19- **Go 1.24+** - High-performance backend server
20- **chi** - Lightweight router
21- **go-git** - Native Git operations
22- **SQLite** (modernc.org/sqlite) - Pure Go database, no CGO required
23- **goth** - GitHub OAuth authentication
24
25### Frontend
26- **Astro** - Fast, client-only static site generation
27- **React 18** - UI components
28- **TipTap** - WYSIWYG markdown editor
29- **shadcn/ui** - Beautiful, accessible components
30- **Tailwind CSS** - Utility-first styling
31- **React Query** - Data fetching and state management
32
33## Quick Start
34
35### Prerequisites
36
37- Docker and Docker Compose installed
38- GitHub OAuth application credentials ([Setup Guide](./SETUP.md))
39
40### Run with Docker
41
421. Clone the repository:
43```bash
44git clone https://github.com/yourusername/markedit.git
45cd markedit
46```
47
482. Copy the environment file and configure:
49```bash
50cp .env.example .env
51# Edit .env with your GitHub OAuth credentials
52```
53
543. Start the application:
55```bash
56make up
57```
58
594. Open your browser to `http://localhost:3000`
60
61That's it! The application will be running with all dependencies containerized.
62
63## Development
64
65### Local Development Setup
66
67#### Backend
68
69Requirements:
70- Go 1.24 or higher
71
72```bash
73cd backend
74cp .env.example .env
75# Edit .env with your credentials
76
77# Run migrations and start server
78go run cmd/server/main.go
79```
80
81The backend will start on `http://localhost:8080`
82
83#### Frontend
84
85Requirements:
86- Bun 1.x or higher
87
88```bash
89cd frontend
90bun install
91bun run dev
92```
93
94The frontend will start on `http://localhost:4321`
95
96## How It Works
97
98### Workflow
99
1001. **Authenticate** - Sign in with your GitHub account
1012. **Select Repository** - Choose the GitHub repo containing your blog posts
1023. **Select Folder** - Optionally specify a folder within the repo
1034. **Edit Files** - Browse and edit markdown files with the WYSIWYG editor
1045. **Auto-save** - Changes are automatically saved as drafts
1056. **Publish** - Create a pull request with your changes
106
107### Git Integration
108
109MarkEdit uses a smart branching strategy:
110
111- Creates timestamped branches: `markedit-{unix_timestamp}`
112- Reuses branches if they're less than 4 hours old
113- Automatically commits your changes with descriptive messages
114- Creates pull requests with your custom title and description
115- Cleans up drafts after successful publication
116
117### Draft System
118
119- All edits are saved as drafts in the SQLite database
120- Drafts are user-specific and file-specific
121- Published changes replace the draft content
122- Drafts are automatically deleted after successful PR creation
123
124## Architecture
125
126```
127markedit/
128├── backend/ # Go server
129│ ├── cmd/server/ # Main entry point
130│ ├── internal/
131│ │ ├── api/ # HTTP handlers
132│ │ ├── auth/ # OAuth & sessions
133│ │ ├── database/ # SQLite & queries
134│ │ ├── git/ # Git operations
135│ │ └── markdown/ # Frontmatter parsing
136│ └── Dockerfile
137├── frontend/ # Astro + React
138│ ├── src/
139│ │ ├── components/
140│ │ ├── lib/ # API client & hooks
141│ │ └── pages/
142│ ├── nginx.conf
143│ └── Dockerfile
144└── docker-compose.yml
145```
146
147## API Endpoints
148
149### Authentication
150- `GET /auth/github` - Initiate GitHub OAuth flow
151- `GET /auth/github/callback` - OAuth callback handler
152- `GET /auth/user` - Get current user info
153- `POST /auth/logout` - Logout current user
154
155### Repositories
156- `GET /api/repos` - List user's repositories
157- `GET /api/repos/:owner/:repo/files` - List files in repository
158- `GET /api/repos/:owner/:repo/files/*path` - Get file content
159- `PUT /api/repos/:owner/:repo/files/*path` - Save draft content
160
161### Git Operations
162- `GET /api/repos/:owner/:repo/branch/status` - Get current branch info
163- `POST /api/repos/:owner/:repo/publish` - Commit, push, and create PR
164
165## Configuration
166
167### Environment Variables
168
169See [SETUP.md](./SETUP.md) for detailed configuration instructions.
170
171**Backend** (`.env`):
172```bash
173GITHUB_CLIENT_ID=your_github_oauth_client_id
174GITHUB_CLIENT_SECRET=your_github_oauth_client_secret
175SESSION_SECRET=random-32-character-string
176DATABASE_PATH=./data/markedit.db
177GIT_CACHE_DIR=./data/repos
178CORS_ALLOWED_ORIGINS=http://localhost:4321,http://localhost:3000
179```
180
181**Frontend** (`frontend/.env`):
182```bash
183PUBLIC_API_URL=http://localhost:8080
184```
185
186## Deployment
187
188### Docker Production Deployment
189
1901. Configure environment variables in `.env`
1912. Build and start containers:
192```bash
193make build
194make up
195```
196
1973. Check logs:
198```bash
199make logs
200```
201
2024. Stop containers:
203```bash
204make down
205```
206
207### Manual Deployment
208
209See [SETUP.md](./SETUP.md) for detailed deployment instructions for various platforms.
210
211## Makefile Commands
212
213```bash
214make build # Build Docker images
215make up # Start containers
216make down # Stop containers
217make restart # Restart containers
218make logs # View logs
219make logs-f # Follow logs
220make clean # Remove containers and volumes
221make shell-be # Access backend shell
222make shell-fe # Access frontend shell
223```
224
225## Design Philosophy
226
227MarkEdit features a distinctive **brutalist/editorial aesthetic**:
228
229- **Typography**: Archivo Black for headings, Crimson Pro for body text
230- **Colors**: Amber/orange accents (#d97706) with strong black borders
231- **Style**: Bold 2px borders, grain texture backgrounds, no gradients
232- **UX**: Clear, direct interactions with immediate feedback
233
234## Security
235
236- OAuth tokens are securely stored and never exposed to the frontend
237- Session cookies are encrypted and HTTP-only
238- File operations are scoped to authenticated user's accessible repos
239- Git operations use the user's GitHub token with appropriate permissions
240
241## Contributing
242
243Contributions are welcome! Please follow these guidelines:
244
2451. Fork the repository
2462. Create a feature branch
2473. Make your changes
2484. Add tests if applicable
2495. Submit a pull request
250
251## License
252
253MIT License - see [LICENSE](./LICENSE) for details
254
255## Support
256
257For detailed setup instructions, see [SETUP.md](./SETUP.md)
258
259For issues and feature requests, please use [GitHub Issues](https://github.com/yourusername/markedit/issues)
260
261## Acknowledgments
262
263- [TipTap](https://tiptap.dev/) - Excellent WYSIWYG editor
264- [go-git](https://github.com/go-git/go-git) - Pure Go git implementation
265- [Astro](https://astro.build/) - Fast static site generator
266- [shadcn/ui](https://ui.shadcn.com/) - Beautiful component library