usaa.ma / markedit
A deployable markdown editor that connects with your self hosted files and lets you edit in a beautiful interface
fork atom
TypeScript 46.6%
Go 45.9%
Astro 4.6%
Makefile 1.2%
Dockerfile 0.8%
CSS 0.6%
JavaScript 0.3%
45 1 0

Clone this repository

https://tangled.org/usaa.ma/markedit https://tangled.org/did:plc:d362ytwol467iybrp3a7evxx/markedit
git@tangled.org:usaa.ma/markedit git@tangled.org:did:plc:d362ytwol467iybrp3a7evxx/markedit

For self-hosted knots, clone URLs may differ based on your setup.

Download tar.gz
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#

  1. Clone the repository:
git clone https://tangled.org/usaa.ma/markedit
cd markedit
  1. Copy the environment file and configure:
cp .env.example .env
# Edit .env with your GitHub OAuth credentials
  1. Start the application:
make up
  1. 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#

  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

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#

  1. Configure environment variables in .env
  2. Build and start containers:
make build
make up
  1. Check logs:
make logs
  1. 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

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#

I am not expecting contributions yet. I will have a guide here once I am ready.

License#

MIT License - see LICENSE for details

Support#

For detailed setup instructions, see SETUP.md

For issues and feature requests, please use Tangled Issues