CodiMD / HedgeDoc

CodiMD (now renamed HedgeDoc) is an open-source, self-hosted platform for real-time collaborative markdown editing. It allows multiple users to simultaneously edit a single markdown document in the browser, seeing each other's changes instantly via WebSocket connections.

HedgeDoc is the community-driven successor to CodiMD, which itself was a fork of the open-source edition of HackMD. The naming history is confusing: HackMD → CodiMD (open-source fork) → HedgeDoc (community rename in 2020). The commercial HackMD product continues as a separate SaaS offering, while HedgeDoc is the fully open-source, self-hosted alternative.

Why self-host collaborative markdown?

• Data sovereignty — Sensitive meeting notes, runbooks, and documentation stay on your infrastructure, not on third-party SaaS
• Real-time collaboration — Google Docs-like experience but for markdown, with syntax highlighting, live preview, and no vendor lock-in
• Developer-friendly — Native support for code blocks, Mermaid diagrams, LaTeX math, slide decks, and other markdown extensions
• Lightweight — A single Node.js process with a database is all you need. Minimal infrastructure compared to a full wiki or CMS
• Integration — Supports LDAP, OAuth2, SAML for enterprise SSO. Export to PDF, HTML, or GitHub Gist

HedgeDoc 1.x is a Node.js application built on Express.js. The architecture is straightforward: a single application process handles HTTP requests, serves the web UI, manages WebSocket connections for real-time collaboration, and communicates with a database for persistence.

Core components

HedgeDoc can be deployed via Docker (recommended), manual Node.js installation, or on Kubernetes. Configuration is done through environment variables or a config.json file.

Docker deployment (recommended)

The official Docker image is the simplest way to run HedgeDoc in production. A docker-compose.yml with HedgeDoc + PostgreSQL is the most common setup:

services:
  hedgedoc:
    image: quay.io/hedgedoc/hedgedoc:1.10.7
    environment:
      - CMD_DB_URL=postgres://hedgedoc:secret@db:5432/hedgedoc
      - CMD_DOMAIN=docs.example.com
      - CMD_PROTOCOL_USESSL=true
      - CMD_URL_ADDPORT=false
      - CMD_ALLOW_ANONYMOUS=false
      - CMD_DEFAULT_PERMISSION=limited
      - CMD_IMAGE_UPLOAD_TYPE=filesystem
    volumes:
      - uploads:/hedgedoc/public/uploads
    ports:
      - "3000:3000"
    depends_on:
      - db
    restart: always

  db:
    image: postgres:17-alpine
    environment:
      - POSTGRES_USER=hedgedoc
      - POSTGRES_PASSWORD=secret
      - POSTGRES_DB=hedgedoc
    volumes:
      - db-data:/var/lib/postgresql/data
    restart: always

volumes:
  uploads:
  db-data:

Manual Node.js install

• Requires Node.js 20+ (Node 18 support was dropped; check HedgeDoc docs for exact version compatibility)
• Clone the repository, run yarn install and yarn build
• Configure via config.json or environment variables prefixed with CMD_
• Use a process manager like systemd or pm2 to keep it running

Kubernetes deployment

• Community Helm charts are available (not officially maintained)
• Key considerations: persistent volume for uploads, database as a StatefulSet or external managed database, WebSocket-aware ingress configuration
• Set CMD_DOMAIN to match the ingress hostname
• If using multiple replicas, you need sticky sessions or a shared session store (Redis) since WebSocket connections are stateful

HedgeDoc provides a rich collaborative editing experience with powerful markdown extensions beyond standard CommonMark.

Real-time collaboration

• Simultaneous editing — Multiple users can edit the same note at the same time. Changes appear instantly for all participants via WebSocket
• Cursor presence — See where other editors are typing in real time
• Conflict resolution — Operational Transformation (OT) handles concurrent edits without conflicts

Markdown extensions

Revision history

Every note maintains a revision history. Users can browse previous versions and see what changed. Revisions are stored in the database and can be configured for automatic cleanup to prevent unbounded growth.

Permissions model

Export options

• Markdown — Download the raw .md file
• HTML — Rendered output as a standalone HTML file
• PDF — Print-ready export (requires browser or additional tooling)
• GitHub Gist — Publish directly to a GitHub Gist
• Reveal.js slides — Export presentations

HedgeDoc supports a wide range of authentication backends, making it easy to integrate into existing enterprise identity infrastructure.

Supported providers

Guest and anonymous access

• CMD_ALLOW_ANONYMOUS=true — Allows anonymous users to create new notes without signing in
• CMD_ALLOW_ANONYMOUS_EDITS=true — Allows anonymous users to edit existing shared notes (if note permissions allow). Works independently of CMD_ALLOW_ANONYMOUS
• CMD_ALLOW_FREEURL=true — Allows creating notes at custom URLs (e.g., /my-meeting-notes)

HedgeDoc requires a database for note content and metadata, and a storage backend for uploaded images and files.

Database options

The database connection is configured via CMD_DB_URL (connection string format) or individual CMD_DB_* environment variables for host, port, username, password, and database name.

Image and file upload storage

HedgeDoc is a low-maintenance application, but production deployments require attention to backups, user management, and monitoring.

User management

• Users are created on first login via the configured authentication provider
• No built-in admin panel in HedgeDoc 1.x — user management is done via the database directly
• Set user roles by updating the Users table: UPDATE "Users" SET "role" = 'admin' WHERE "email" = 'admin@example.com';
• Deactivated users can be removed from the database, but their notes persist (owned by a deleted user)

Note cleanup

• Old, unused notes accumulate over time. There is no built-in auto-cleanup
• Write a periodic job to identify and archive notes not accessed in X months
• Revision history can grow large; consider pruning old revisions from the Revisions table

Backup strategies

# PostgreSQL backup
pg_dump -U hedgedoc -h localhost hedgedoc | gzip > hedgedoc_$(date +%Y%m%d).sql.gz

# Restore
gunzip -c hedgedoc_20260319.sql.gz | psql -U hedgedoc -h localhost hedgedoc

# Backup uploads (local filesystem)
tar -czf hedgedoc_uploads_$(date +%Y%m%d).tar.gz /hedgedoc/public/uploads/

Monitoring and health checks

• Health endpoint — GET /_health is a lightweight health check endpoint ideal for load balancers. GET /status returns more detailed instance information including online users and note count
• Metrics — HedgeDoc exposes a Prometheus-compatible endpoint at GET /metrics (since 1.8.0), providing the same stats as /status plus Node.js performance figures. Disable with enableStatsApi: false in config if not needed
• Resource monitoring — Watch Node.js memory usage (can grow with many concurrent WebSocket connections), database connection pool, and disk usage for uploads

HedgeDoc 2.x is a ground-up rewrite of the application. It is not a simple upgrade from 1.x — it is an entirely new codebase with a different architecture, different API, and different feature set.

Architecture comparison

Key changes in 2.x

• CRDT instead of OT — 2.x uses Y.js (Conflict-free Replicated Data Type) for real-time sync. This is more robust than Operational Transform and enables offline editing with later sync
• Separate frontend and backend — The React frontend communicates with the NestJS backend via a well-defined API. This enables alternative frontends and better API-first integrations
• Modern editor — CodeMirror 6 provides better mobile support, accessibility, and extensibility
• No direct migration path — There is no automated migration tool from 1.x to 2.x as of early 2026. Notes must be exported and re-imported

What to tell clients

• Deploy HedgeDoc 1.x for production use today
• The 1.x branch continues to receive security fixes and minor updates
• Plan for an eventual migration to 2.x, but do not block on it
• If the client needs features only in 2.x (offline editing, better mobile), evaluate the alpha carefully and accept the risk