# MarkEdit

A 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.

## Features

- **🎨 Beautiful WYSIWYG Editor** - Rich text editing powered by TipTap with markdown support
- **📝 Frontmatter Support** - Edit YAML frontmatter metadata alongside your content
- **💾 Auto-save** - Changes are automatically saved as drafts every 2 seconds
- **🔄 Git Integration** - Automatic branching, commits, and pull request creation
- **🔐 GitHub OAuth** - Secure authentication with your GitHub account
- **📂 Multi-repo Support** - Work with multiple repositories and folder structures
- **⚡ Fast & Lightweight** - Built with modern technologies for optimal performance
- **🐳 Docker Ready** - Easy deployment with Docker and docker-compose

## Tech Stack

### Backend
- **Go 1.24+** - High-performance backend server
- **chi** - Lightweight router
- **go-git** - Native Git operations
- **SQLite** (modernc.org/sqlite) - Pure Go database, no CGO required
- **goth** - GitHub OAuth authentication

### Frontend
- **Astro** - Fast, client-only static site generation
- **React 18** - UI components
- **TipTap** - WYSIWYG markdown editor
- **shadcn/ui** - Beautiful, accessible components
- **Tailwind CSS** - Utility-first styling
- **React Query** - Data fetching and state management

## Quick Start

### Prerequisites

- Docker and Docker Compose installed
- GitHub OAuth application credentials ([Setup Guide](./SETUP.md))

### Run with Docker

1. Clone the repository:
```bash
git clone https://github.com/yourusername/markedit.git
cd markedit
```

2. Copy the environment file and configure:
```bash
cp .env.example .env
# Edit .env with your GitHub OAuth credentials
```

3. Start the application:
```bash
make up
```

4. Open your browser to `http://localhost:3000`

That's it! The application will be running with all dependencies containerized.

## Development

### Local Development Setup

#### Backend

Requirements:
- Go 1.24 or higher

```bash
cd backend
cp .env.example .env
# Edit .env with your credentials

# Run migrations and start server
go run cmd/server/main.go
```

The backend will start on `http://localhost:8080`

#### Frontend

Requirements:
- Bun 1.x or higher

```bash
cd frontend
bun install
bun run dev
```

The frontend will start on `http://localhost:4321`

## How It Works

### Workflow

1. **Authenticate** - Sign in with your GitHub account
2. **Select Repository** - Choose the GitHub repo containing your blog posts
3. **Select Folder** - Optionally specify a folder within the repo
4. **Edit Files** - Browse and edit markdown files with the WYSIWYG editor
5. **Auto-save** - Changes are automatically saved as drafts
6. **Publish** - Create a pull request with your changes

### Git Integration

MarkEdit uses a smart branching strategy:

- Creates timestamped branches: `markedit-{unix_timestamp}`
- Reuses branches if they're less than 4 hours old
- Automatically commits your changes with descriptive messages
- Creates pull requests with your custom title and description
- Cleans up drafts after successful publication

### Draft System

- All edits are saved as drafts in the SQLite database
- Drafts are user-specific and file-specific
- Published changes replace the draft content
- Drafts are automatically deleted after successful PR creation

## Architecture

```
markedit/
├── backend/           # Go server
│   ├── cmd/server/    # Main entry point
│   ├── internal/
│   │   ├── api/       # HTTP handlers
│   │   ├── auth/      # OAuth & sessions
│   │   ├── database/  # SQLite & queries
│   │   ├── git/       # Git operations
│   │   └── markdown/  # Frontmatter parsing
│   └── Dockerfile
├── frontend/          # Astro + React
│   ├── src/
│   │   ├── components/
│   │   ├── lib/       # API client & hooks
│   │   └── pages/
│   ├── nginx.conf
│   └── Dockerfile
└── docker-compose.yml
```

## API Endpoints

### Authentication
- `GET /auth/github` - Initiate GitHub OAuth flow
- `GET /auth/github/callback` - OAuth callback handler
- `GET /auth/user` - Get current user info
- `POST /auth/logout` - Logout current user

### Repositories
- `GET /api/repos` - List user's repositories
- `GET /api/repos/:owner/:repo/files` - List files in repository
- `GET /api/repos/:owner/:repo/files/*path` - Get file content
- `PUT /api/repos/:owner/:repo/files/*path` - Save draft content

### Git Operations
- `GET /api/repos/:owner/:repo/branch/status` - Get current branch info
- `POST /api/repos/:owner/:repo/publish` - Commit, push, and create PR

## Configuration

### Environment Variables

See [SETUP.md](./SETUP.md) for detailed configuration instructions.

**Backend** (`.env`):
```bash
GITHUB_CLIENT_ID=your_github_oauth_client_id
GITHUB_CLIENT_SECRET=your_github_oauth_client_secret
SESSION_SECRET=random-32-character-string
DATABASE_PATH=./data/markedit.db
GIT_CACHE_DIR=./data/repos
CORS_ALLOWED_ORIGINS=http://localhost:4321,http://localhost:3000
```

**Frontend** (`frontend/.env`):
```bash
PUBLIC_API_URL=http://localhost:8080
```

## Deployment

### Docker Production Deployment

1. Configure environment variables in `.env`
2. Build and start containers:
```bash
make build
make up
```

3. Check logs:
```bash
make logs
```

4. Stop containers:
```bash
make down
```

### Manual Deployment

See [SETUP.md](./SETUP.md) for detailed deployment instructions for various platforms.

## Makefile Commands

```bash
make build       # Build Docker images
make up          # Start containers
make down        # Stop containers
make restart     # Restart containers
make logs        # View logs
make logs-f      # Follow logs
make clean       # Remove containers and volumes
make shell-be    # Access backend shell
make shell-fe    # Access frontend shell
```

## Design Philosophy

MarkEdit features a distinctive **brutalist/editorial aesthetic**:

- **Typography**: Archivo Black for headings, Crimson Pro for body text
- **Colors**: Amber/orange accents (#d97706) with strong black borders
- **Style**: Bold 2px borders, grain texture backgrounds, no gradients
- **UX**: Clear, direct interactions with immediate feedback

## Security

- OAuth tokens are securely stored and never exposed to the frontend
- Session cookies are encrypted and HTTP-only
- File operations are scoped to authenticated user's accessible repos
- Git operations use the user's GitHub token with appropriate permissions

## Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT License - see [LICENSE](./LICENSE) for details

## Support

For detailed setup instructions, see [SETUP.md](./SETUP.md)

For issues and feature requests, please use [GitHub Issues](https://github.com/yourusername/markedit/issues)

## Acknowledgments

- [TipTap](https://tiptap.dev/) - Excellent WYSIWYG editor
- [go-git](https://github.com/go-git/go-git) - Pure Go git implementation
- [Astro](https://astro.build/) - Fast static site generator
- [shadcn/ui](https://ui.shadcn.com/) - Beautiful component library