A deployable markdown editor that connects with your self hosted files and lets you edit in a beautiful interface

README.md

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

Quick Start #

Prerequisites #

Docker and Docker Compose installed
GitHub OAuth application credentials (Setup Guide)

Run with Docker #

Clone the repository:

git clone https://tangled.org/usaa.ma/markedit
cd markedit

Copy the environment file and configure:

cp .env.example .env
# Edit .env with your GitHub OAuth credentials

Start the application:

make up

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

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

cd frontend
bun install
bun run dev

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

How It Works #

Workflow #

Authenticate - Sign in with your GitHub account
Select Repository - Choose the GitHub repo containing your blog posts
Select Folder - Optionally specify a folder within the repo
Edit Files - Browse and edit markdown files with the WYSIWYG editor
Auto-save - Changes are automatically saved as drafts
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

Configuration #

Environment Variables #

See SETUP.md for detailed configuration instructions.

Backend (.env):

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):

PUBLIC_API_URL=http://localhost:8080

Deployment #

Docker Production Deployment #

Configure environment variables in .env
Build and start containers:

make build
make up

Check logs:

make logs

Stop containers:

make down

Manual Deployment #

See SETUP.md for detailed deployment instructions for various platforms.

Makefile Commands #

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