# HedgeDoc Collaborative Markdown

> HedgeDoc for collaborative markdown editing with PostgreSQL.

- Category: Productivity & Collaboration
- Difficulty: beginner
- Components: hedgedoc, postgresql
- Tags: hedgedoc, markdown, collaboration, notes, real-time
- Source: https://docker.recipes/productivity/hedgedoc-markdown

## Overview

HedgeDoc is a modern, open-source collaborative markdown editor that evolved from HackMD, designed to enable real-time collaborative document creation and editing. It transforms markdown editing from a solitary activity into a dynamic team experience, supporting simultaneous editing by multiple users with live cursor tracking, change highlighting, and instant synchronization. HedgeDoc excels at technical documentation, meeting notes, project planning, and any scenario where teams need to collaborate on structured text content in real-time. This stack combines HedgeDoc with PostgreSQL to create a robust, production-ready collaborative writing platform. PostgreSQL provides enterprise-grade data integrity and ACID compliance for storing document content, revision history, and user data - crucial for collaborative environments where document consistency and data reliability are paramount. The relational structure of PostgreSQL efficiently handles HedgeDoc's complex relationships between users, documents, permissions, and collaborative sessions, while its advanced indexing capabilities ensure fast document retrieval even with large document repositories. This combination serves development teams, technical writers, educators, and organizations that need reliable collaborative documentation tools with professional-grade data persistence. The PostgreSQL backend ensures that collaborative sessions remain consistent even under heavy concurrent editing loads, while HedgeDoc's real-time synchronization engine provides the responsive editing experience users expect from modern collaborative platforms.

## Features

- Real-time collaborative editing with live cursor tracking and user presence indicators
- Comprehensive markdown support including tables, code blocks, math equations, and diagrams
- Built-in presentation mode for converting markdown documents into slideshow presentations
- Document permission system with view, edit, and share controls for team collaboration
- PostgreSQL-backed revision history with full document versioning and change tracking
- Anonymous editing support for public collaboration without account requirements
- File upload system with persistent storage for images and attachments
- Multi-user concurrent editing with conflict resolution and operational transformation

## Use cases

- Software development teams creating and maintaining technical documentation collaboratively
- Educational institutions enabling students and faculty to work together on research papers and course materials
- Remote teams conducting real-time meeting notes and project planning sessions
- Open source projects managing community-driven documentation and contribution guidelines
- Technical writing teams creating API documentation, user guides, and knowledge bases
- Startups and small businesses maintaining internal wikis and process documentation
- Conference organizers collaborating on speaker notes, schedules, and presentation materials

## Prerequisites

- Docker and Docker Compose installed with at least 2GB available RAM for optimal performance
- Port 3000 available for HedgeDoc web interface access
- Basic understanding of markdown syntax for effective document creation
- Network access configuration if deploying for team access beyond localhost
- SSL certificate and reverse proxy setup for production deployments with external access
- Backup strategy for PostgreSQL data volume to prevent document loss

## docker-compose.yml

```yaml
services:
  postgres:
    image: postgres:16-alpine
    container_name: hedgedoc-postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-hedgedoc}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-hedgedoc}
      POSTGRES_DB: ${POSTGRES_DB:-hedgedoc}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - hedgedoc-network

  hedgedoc:
    image: quay.io/hedgedoc/hedgedoc:latest
    container_name: hedgedoc
    restart: unless-stopped
    ports:
      - "${HEDGEDOC_PORT:-3000}:3000"
    environment:
      - CMD_DB_URL=postgres://${POSTGRES_USER:-hedgedoc}:${POSTGRES_PASSWORD:-hedgedoc}@postgres:5432/${POSTGRES_DB:-hedgedoc}
      - CMD_DOMAIN=${DOMAIN:-localhost}
      - CMD_URL_ADDPORT=${ADD_PORT:-true}
      - CMD_PROTOCOL_USESSL=false
      - CMD_ALLOW_ANONYMOUS=${ALLOW_ANON:-true}
      - CMD_ALLOW_ANONYMOUS_EDITS=${ALLOW_ANON_EDIT:-true}
    volumes:
      - hedgedoc_uploads:/hedgedoc/public/uploads
    depends_on:
      - postgres
    networks:
      - hedgedoc-network

volumes:
  postgres_data:
  hedgedoc_uploads:

networks:
  hedgedoc-network:
    driver: bridge
```

## .env

```bash
# HedgeDoc
HEDGEDOC_PORT=3000
DOMAIN=localhost
ADD_PORT=true
POSTGRES_USER=hedgedoc
POSTGRES_PASSWORD=hedgedoc
POSTGRES_DB=hedgedoc
ALLOW_ANON=true
ALLOW_ANON_EDIT=true
```

## Usage notes

- HedgeDoc at http://localhost:3000
- Create notes with /new
- Real-time collaboration
- Supports presentations

## Troubleshooting

- HedgeDoc shows database connection errors: Verify PostgreSQL container is running and environment variables match between services
- Real-time collaboration not working properly: Check that WebSocket connections aren't blocked by firewall or proxy settings
- File uploads failing or images not displaying: Ensure hedgedoc_uploads volume has proper write permissions and sufficient disk space
- Anonymous editing disabled unexpectedly: Verify CMD_ALLOW_ANONYMOUS and CMD_ALLOW_ANONYMOUS_EDITS environment variables are set to true
- PostgreSQL container fails to start with data corruption: Stop containers, remove postgres_data volume, and restart to reinitialize database
- HedgeDoc performance degrading with many concurrent users: Increase PostgreSQL shared_buffers and work_mem settings, monitor connection pool limits

