Self-Host HedgeDoc: Collaborative Markdown Editor 2026

TL;DR

HedgeDoc (AGPL 3.0, ~5K GitHub stars, TypeScript) is a real-time collaborative Markdown editor. Multiple people edit the same document simultaneously with live preview — like Google Docs, but for Markdown. Code blocks with syntax highlighting, Mermaid diagrams, LaTeX math, and even presentation mode (turn any document into slides). HackMD charges $5/user/month for team features; HedgeDoc is free with unlimited users and documents.

Key Takeaways

• HedgeDoc: AGPL 3.0, ~5K stars, TypeScript — collaborative Markdown editor
• Real-time collaboration: Multiple editors at once with live cursors
• Markdown++: Code blocks, Mermaid diagrams, LaTeX math, Vega charts
• Presentation mode: Turn any document into slides with --- separators
• Permissions: Public, editable, locked, private — per document
• Export: HTML, PDF, raw Markdown, EPUB

---

HedgeDoc vs HackMD vs Google Docs vs Etherpad

Feature	HedgeDoc	HackMD	Google Docs	Etherpad
Format	Markdown	Markdown	Rich text	Rich text
Real-time collab	Yes	Yes	Yes	Yes
Self-hosted	Yes	No (mostly)	No	Yes
Code highlighting	Yes (100+ languages)	Yes	No	No
Diagrams	Mermaid, PlantUML	Mermaid	No	No
Math formulas	LaTeX (MathJax)	LaTeX	Equation editor	No
Presentations	Yes	Yes	Separate tool	No
Price	Free	$5/user/mo	Free (cloud)	Free

---

Part 1: Docker Setup

# docker-compose.yml
services:
  hedgedoc:
    image: quay.io/hedgedoc/hedgedoc:latest
    container_name: hedgedoc
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - hedgedoc_uploads:/hedgedoc/public/uploads
    environment:
      CMD_DB_URL: "postgres://hedgedoc:${DB_PASSWORD}@db:5432/hedgedoc"
      CMD_DOMAIN: docs.yourdomain.com
      CMD_PROTOCOL_USESSL: "true"
      CMD_URL_ADDPORT: "false"
      CMD_SESSION_SECRET: "${SESSION_SECRET}"   # openssl rand -hex 32

      # Registration:
      CMD_ALLOW_EMAIL_REGISTER: "true"    # Set to false after creating your account
      CMD_ALLOW_ANONYMOUS: "false"
      CMD_ALLOW_ANONYMOUS_EDITS: "true"   # Allow anonymous users to edit shared docs

      # Default permission for new notes:
      CMD_DEFAULT_PERMISSION: "editable"  # freely, editable, limited, locked, protected, private

      # Image upload:
      CMD_IMAGE_UPLOAD_TYPE: filesystem

    depends_on:
      - db

  db:
    image: postgres:16-alpine
    restart: unless-stopped
    volumes:
      - hedgedoc_db:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: hedgedoc
      POSTGRES_PASSWORD: "${DB_PASSWORD}"
      POSTGRES_DB: hedgedoc

volumes:
  hedgedoc_uploads:
  hedgedoc_db:

echo "DB_PASSWORD=$(openssl rand -base64 24)" >> .env
echo "SESSION_SECRET=$(openssl rand -hex 32)" >> .env

docker compose up -d

---

Part 2: HTTPS with Caddy

docs.yourdomain.com {
    reverse_proxy localhost:3000
}

---

Writing in HedgeDoc: Features Overview

Creating a Document

To create a new document, click "+ New Note" in the HedgeDoc interface or navigate directly to your instance's /new path. The editor opens in split view by default: the left panel shows the raw Markdown source and the right panel shows the live rendered preview. You can toggle between three view modes — editor only, split view, and preview only — using the buttons in the toolbar.

Code Blocks with Syntax Highlighting

HedgeDoc supports syntax-highlighted code blocks with over 100 programming languages. To create a code block, use three backticks followed by the language name on the same line, then write your code, then close with three backticks on their own line. For example, you would specify python, rust, javascript, go, typescript, bash, yaml, sql, or any of over a hundred other supported languages after the opening backticks. HedgeDoc uses highlight.js to render syntax highlighting in the preview panel, so colors and keyword emphasis update in real time as you type.

For shell commands and scripts, the bash or sh language identifier provides appropriate highlighting for commands, flags, and variable substitutions. For configuration files, yaml and toml identifiers highlight structure and values clearly. For infrastructure-as-code, terraform and hcl are supported. The syntax highlighting renders correctly when documents are exported as HTML or converted to PDF.

Mermaid Diagrams

HedgeDoc renders Mermaid diagrams directly in the preview panel. To add a diagram, create a code block with the language identifier set to mermaid, then write your diagram definition inside the block. HedgeDoc supports all major Mermaid diagram types: flowcharts (using graph TD or graph LR syntax for top-down or left-right orientation), sequence diagrams (using sequenceDiagram), entity relationship diagrams, class diagrams, state diagrams, Gantt charts, and pie charts.

A flowchart in Mermaid describes nodes and the arrows between them. Each node gets a label in brackets, and arrows use syntax like A-->B for a plain arrow or A-->|label|B to add text to the connection. Sequence diagrams describe message flows between named participants using arrow notation like Participant1->>Participant2: Message text. These render as visually clear boxes and arrows in HedgeDoc's preview without any external tools or plugins.

PlantUML diagrams are also supported using the plantuml code block identifier, which expands the diagram types available beyond what Mermaid covers — including UML class hierarchies, activity diagrams, and deployment diagrams.

LaTeX Math Formulas

HedgeDoc renders LaTeX mathematical notation using MathJax. Inline math uses single dollar signs around the expression, so the LaTeX for E equals mc squared renders as a formatted equation inline with surrounding text. Block-level equations use double dollar signs on their own lines, centering the rendered formula with full display formatting. This is essential for scientific and engineering documentation where notation must be precise and readable — supporting integration symbols, summations, matrices, fractions, Greek letters, and the full LaTeX math symbol set.

Tables and Admonitions

Markdown tables render with alternating row colors in HedgeDoc's preview. The pipe-delimited table syntax — a header row, a separator row with dashes, and data rows — produces clean aligned tables that look professional in both the preview and when exported.

HedgeDoc supports admonition blocks for callouts and notices, using triple-colon syntax with a type keyword. The supported types are info, warning, danger, and success — each renders with a colored background and an appropriate icon in the preview. These are useful for adding notes, warnings, and tips to technical documentation without relying on workarounds like bold text or emoji.

---

Presentation Mode

HedgeDoc can turn any Markdown document into a presentation using the reveal.js library. To define slide boundaries, use a line containing only three hyphens (the horizontal rule separator) between sections of content. Each section between separators becomes one slide in the presentation. The presentation reads the document's YAML frontmatter for slide configuration options including theme, transition style, and background colors.

To launch presentation mode, click the presentation icon in the document toolbar — it looks like a small screen or monitor icon. The editor transitions to a full-screen reveal.js presentation. Keyboard navigation (arrow keys or spacebar) moves between slides. The presenter view shows a timer, speaker notes, and a preview of the next slide.

Slides can contain any content that HedgeDoc renders: formatted text, code blocks with syntax highlighting, Mermaid diagrams, LaTeX equations, images, and tables. This makes HedgeDoc particularly useful for technical presentations where embedding live code examples, architecture diagrams, and mathematical notation is important. Teams that write runbooks or incident response documents in HedgeDoc can turn those same documents into presentation-ready materials for postmortems or knowledge sharing sessions without reformatting.

Vertical slides allow nested slide hierarchies: a section heading becomes a horizontal slide, and subsections within it become vertical slides accessible by pressing the down arrow. This is useful for talks that cover multiple top-level topics with drill-down detail available for each.

The export options for presentations include downloading the slides as an HTML file that can be served statically or opened locally, and a PDF export through the browser's print dialog using reveal.js's print CSS. Both options preserve the styling and formatting of the presentation without requiring the HedgeDoc server to remain running for playback.

---

Part 5: Permissions

Per-document permissions

Permission	View	Edit	Owner
Freely	Anyone	Anyone	Creator
Editable	Anyone	Logged-in users	Creator
Limited	Logged-in users	Logged-in users	Creator
Locked	Logged-in users	Owner only	Creator
Protected	Logged-in users	Owner only	Creator
Private	Owner only	Owner only	Creator

Share a document

https://docs.yourdomain.com/abc123

Share the URL — permission controls who can view/edit.

Publish a document

1. Click Publish → generates a read-only URL
2. Published URL: https://docs.yourdomain.com/s/abc123
3. Clean rendered view without editor

---

Part 6: OAuth2 / SSO

Login with Authentik

environment:
  CMD_OAUTH2_PROVIDERNAME: Authentik
  CMD_OAUTH2_CLIENT_ID: hedgedoc-client-id
  CMD_OAUTH2_CLIENT_SECRET: hedgedoc-client-secret
  CMD_OAUTH2_AUTHORIZATION_URL: https://auth.yourdomain.com/application/o/authorize/
  CMD_OAUTH2_TOKEN_URL: https://auth.yourdomain.com/application/o/token/
  CMD_OAUTH2_USER_PROFILE_URL: https://auth.yourdomain.com/application/o/userinfo/
  CMD_OAUTH2_SCOPE: "openid email profile"
  CMD_OAUTH2_USER_PROFILE_USERNAME_ATTR: preferred_username
  CMD_OAUTH2_USER_PROFILE_DISPLAY_NAME_ATTR: name
  CMD_OAUTH2_USER_PROFILE_EMAIL_ATTR: email

Login with GitHub

environment:
  CMD_GITHUB_CLIENTID: your-github-client-id
  CMD_GITHUB_CLIENTSECRET: your-github-client-secret

---

Part 7: API

BASE="https://docs.yourdomain.com"

# Create a new note:
curl -X POST "$BASE/new" \
  -H "Content-Type: text/markdown" \
  -d "# My New Document

This was created via API."

# Get note content:
curl "$BASE/abc123/download"

# Export as HTML:
curl "$BASE/abc123/html" -o document.html

# Export as PDF (if configured):
curl "$BASE/abc123/pdf" -o document.pdf

---

Part 8: Use Cases

Meeting notes

1. Create a shared document before the meeting
2. Share URL with attendees
3. Everyone takes notes simultaneously
4. Notes are saved automatically — no "someone forgot to share the doc"

Technical documentation

1. Write docs in Markdown with diagrams and code blocks
2. Publish as read-only pages
3. Embed diagrams and architecture decisions
4. Version history included

Team standups

# Standup - March 9, 2026

## Alice
- ✅ Finished auth migration
- 🔄 Working on API rate limiting
- 🚫 Blocked on staging environment

## Bob
- ✅ Fixed deployment pipeline
- 🔄 Writing integration tests
- 🚫 No blockers

Decision records

Use HedgeDoc for Architecture Decision Records (ADRs):

# ADR-001: Use PostgreSQL for primary database

## Status: Accepted
## Date: 2026-03-09

## Context
We need a relational database...

## Decision
PostgreSQL 16...

## Consequences
- ✅ Strong consistency
- ❌ Requires backup strategy

---

Maintenance

# Update:
docker compose pull
docker compose up -d

# Backup database:
docker exec hedgedoc-db-1 pg_dump -U hedgedoc hedgedoc \
  | gzip > hedgedoc-db-$(date +%Y%m%d).sql.gz

# Backup uploads:
tar -czf hedgedoc-uploads-$(date +%Y%m%d).tar.gz \
  $(docker volume inspect hedgedoc_hedgedoc_uploads --format '{{.Mountpoint}}')

# Logs:
docker compose logs -f hedgedoc

Choosing HedgeDoc for Your Team

HedgeDoc occupies a specific niche: real-time collaborative Markdown editing, self-hosted. Before deploying it, it's worth understanding where it fits relative to adjacent tools and what makes it the right choice for technical teams in particular.

The comparison to Google Docs is the most natural one. Google Docs handles real-time collaboration well, has excellent mobile support, and requires zero setup. HedgeDoc's advantage is format: Markdown with extended syntax. For teams where documents regularly include code blocks, architecture diagrams, mathematical notation, or need to be exported and version-controlled as text files, Markdown is a fundamentally better format than rich text. Google Docs produces rich text that doesn't convert cleanly to Markdown; HedgeDoc produces Markdown that renders cleanly and stores well in git.

Etherpad is another common comparison. Both are self-hosted collaborative editors, but Etherpad uses rich text while HedgeDoc uses Markdown. Etherpad is simpler to run and has a smaller footprint, but it lacks syntax highlighting, diagram support, and presentation mode. For developer teams, HedgeDoc's Markdown features make it significantly more useful for technical documentation.

HackMD is the closest cloud equivalent to HedgeDoc — HedgeDoc actually originated as a fork of HackMD's open source codebase. HackMD's team features (workspaces, teams, access control) are behind its paid plans at $5/user/month. HedgeDoc gives you the same core editing experience self-hosted, with unlimited users and documents, for the cost of a VPS.

The sweet spots for HedgeDoc are meeting notes (everyone edits simultaneously during the meeting), technical runbooks and incident response documents (updated in real time as situations evolve), and internal documentation that benefits from Markdown's expressiveness without the weight of a full wiki platform like Outline or Bookstack. For comparison between these wiki-level tools, the best open source note-taking and wiki tools guide covers the spectrum from lightweight editors to full knowledge bases.

Why Self-Host HedgeDoc?

The case for self-hosting HedgeDoc comes down to three practical factors: data ownership, cost at scale, and operational control.

Data ownership is the fundamental argument. When you use a SaaS version of any tool, your data lives on someone else's infrastructure subject to their terms of service, their security practices, and their business continuity. If the vendor raises prices, gets acquired, changes API limits, or shuts down, you're left scrambling. Self-hosting HedgeDoc means your data and configuration stay on infrastructure you control — whether that's a VPS, a bare metal server, or a home lab.

Cost at scale matters once you move beyond individual use. Most SaaS equivalents charge per user or per data volume. A self-hosted instance on a $10-20/month VPS typically costs less than per-user SaaS pricing for teams of five or more — and the cost doesn't scale linearly with usage. One well-configured server handles dozens of users for a flat monthly fee.

Operational control is the third factor. The Docker Compose configuration above exposes every setting that commercial equivalents often hide behind enterprise plans: custom networking, environment variables, storage backends, and authentication integrations. You decide when to update, how to configure backups, and what access controls to apply.

The honest tradeoff: you're responsible for updates, backups, and availability. For teams running any production workloads, this is familiar territory. For individuals, the learning curve is real but the tooling (Docker, Caddy, automated backups) is well-documented and widely supported.

Server Requirements and Sizing

Before deploying HedgeDoc, assess your server capacity against expected workload.

Minimum viable setup: A 1 vCPU, 1GB RAM VPS with 20GB SSD is sufficient for personal use or small teams. Most consumer VPS providers — Hetzner, DigitalOcean, Linode, Vultr — offer machines in this range for $5-10/month. Hetzner offers excellent price-to-performance for European and US regions.

Recommended production setup: 2 vCPUs with 4GB RAM and 40GB SSD handles most medium deployments without resource contention. This gives HedgeDoc headroom for background tasks, caching, and concurrent users while leaving capacity for other services on the same host.

Storage planning: The Docker volumes in this docker-compose.yml store all persistent HedgeDoc data. Estimate your storage growth rate early — for data-intensive tools, budget for 3-5x your initial estimate. Hetzner Cloud and Vultr both support online volume resizing without stopping your instance.

Operating system: Any modern 64-bit Linux distribution works. Ubuntu 22.04 LTS and Debian 12 are the most commonly tested configurations. Ensure Docker Engine 24.0+ and Docker Compose v2 are installed — verify with docker --version and docker compose version. Avoid Docker Desktop on production Linux servers; it adds virtualization overhead and behaves differently from Docker Engine in ways that cause subtle networking issues.

Network: Only ports 80 and 443 need to be publicly accessible when running behind a reverse proxy. Internal service ports should be bound to localhost only. A minimal UFW firewall that blocks all inbound traffic except SSH, HTTP, and HTTPS is the single most effective security measure for a self-hosted server.

Backup and Disaster Recovery

Running HedgeDoc without a tested backup strategy is an unacceptable availability risk. Docker volumes are not automatically backed up — if you delete a volume or the host fails, data is gone with no recovery path.

What to back up: The named Docker volumes containing HedgeDoc's data (database files, user uploads, application state), your docker-compose.yml and any customized configuration files, and .env files containing secrets.

Backup approach: For simple setups, stop the container, archive the volume contents, then restart. For production environments where stopping causes disruption, use filesystem snapshots or database dump commands (PostgreSQL pg_dump, SQLite .backup, MySQL mysqldump) that produce consistent backups without downtime.

For a complete automated backup workflow that ships snapshots to S3-compatible object storage, see the Restic + Rclone backup guide. Restic handles deduplication and encryption; Rclone handles multi-destination uploads. The same setup works for any Docker volume.

Backup cadence: Daily backups to remote storage are a reasonable baseline for actively used tools. Use a 30-day retention window minimum — long enough to recover from mistakes discovered weeks later. For critical data, extend to 90 days and use a secondary destination.

Restore testing: A backup that has never been restored is a backup you cannot trust. Once a month, restore your HedgeDoc backup to a separate Docker Compose stack on different ports and verify the data is intact. This catches silent backup failures, script errors, and volume permission issues before they matter in a real recovery.

Security Hardening

Self-hosting means you are responsible for HedgeDoc's security posture. The Docker Compose setup provides a functional base; production deployments need additional hardening.

Always use a reverse proxy: Never expose HedgeDoc's internal port directly to the internet. The docker-compose.yml binds to localhost; Caddy or Nginx provides HTTPS termination. Direct HTTP access transmits credentials in plaintext. A reverse proxy also centralizes TLS management, rate limiting, and access logging.

Strong credentials: Change default passwords immediately after first login. For secrets in docker-compose environment variables, generate random values with openssl rand -base64 32 rather than reusing existing passwords.

Firewall configuration:

ufw default deny incoming
ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable

Internal service ports (databases, admin panels, internal APIs) should only be reachable from localhost or the Docker network, never directly from the internet.

Network isolation: Docker Compose named networks keep HedgeDoc's services isolated from other containers on the same host. Database containers should not share networks with containers that don't need direct database access.

VPN access for sensitive services: For internal-only tools, restricting access to a VPN adds a strong second layer. Headscale is an open source Tailscale control server that puts your self-hosted stack behind a WireGuard mesh, eliminating public internet exposure for internal tools.

Update discipline: Subscribe to HedgeDoc's GitHub releases page to receive security advisory notifications. Schedule a monthly maintenance window to pull updated images. Running outdated container images is the most common cause of self-hosted service compromises.

Troubleshooting Common Issues

Container exits immediately or won't start

Check logs first — they almost always explain the failure:

docker compose logs -f hedgedoc

Common causes: a missing required environment variable, a port already in use, or a volume permission error. Port conflicts appear as bind: address already in use. Find the conflicting process with ss -tlpn | grep PORT and either stop it or change HedgeDoc's port mapping in docker-compose.yml.

Cannot reach the web interface

Work through this checklist:

1. Confirm the container is running: docker compose ps
2. Test locally on the server: curl -I http://localhost:PORT
3. If local access works but external doesn't, check your firewall: ufw status
4. If using a reverse proxy, verify it's running and the config is valid: caddy validate --config /etc/caddy/Caddyfile

Permission errors on volume mounts

Some containers run as a non-root user. If the Docker volume is owned by root, the container process cannot write to it. Find the volume's host path with docker volume inspect VOLUME_NAME, check the tool's documentation for its expected UID, and apply correct ownership:

chown -R 1000:1000 /var/lib/docker/volumes/your_volume/_data

High resource usage over time

Memory or CPU growing continuously usually indicates unconfigured log rotation, an unbound cache, or accumulated data needing pruning. Check current usage with docker stats hedgedoc. Add resource limits in docker-compose.yml to prevent one container from starving others. For ongoing visibility into resource trends, deploy Prometheus + Grafana or Netdata.

Data disappears after container restart

Data stored in the container's writable layer — rather than a named volume — is lost when the container is removed or recreated. This happens when the volume mount path in docker-compose.yml doesn't match where the application writes data. Verify mount paths against the tool's documentation and correct the mapping. Named volumes persist across container removal; only docker compose down -v deletes them.

Keeping HedgeDoc Updated

HedgeDoc follows a regular release cadence. Staying current matters for security patches and compatibility. The update process with Docker Compose is straightforward:

docker compose pull          # Download updated images
docker compose up -d         # Restart with new images
docker image prune -f        # Remove old image layers (optional)

Read the changelog before major version updates. Some releases include database migrations or breaking configuration changes. For major version bumps, test in a staging environment first — run a copy of the service on different ports with the same volume data to validate the migration before touching production.

Version pinning: For stability, pin to a specific image tag in docker-compose.yml instead of latest. Update deliberately after reviewing the changelog. This trades automatic patch delivery for predictable behavior — the right call for business-critical services.

Post-update verification: After updating, confirm HedgeDoc is functioning correctly. Most services expose a /health endpoint that returns HTTP 200 — curl it from the server or monitor it with your uptime tool.

Migrating From HackMD or Other Markdown Editors

If your team is currently using HackMD, Notion, or another Markdown-capable tool and migrating to self-hosted HedgeDoc, the migration path is straightforward because the content format is plain text.

For HackMD migrations, export documents as Markdown files. HackMD's workspace export produces a ZIP of .md files. Each file can be imported into HedgeDoc by creating a new document and pasting the Markdown content, or by using HedgeDoc's API to create documents programmatically from the exported files. For workspaces with hundreds of documents, write a small script that iterates over the ZIP contents and POST each to HedgeDoc's note creation endpoint.

For teams moving from Notion, export pages as Markdown (Notion's Markdown export is imperfect but workable for most content). Tables and code blocks export cleanly; Notion databases become static Markdown tables; embedded content becomes placeholder links. The formatting differences are worth reviewing before bulk import.

For teams using Confluence, exporting to Markdown requires either a paid Confluence plugin or a conversion tool like pandoc. Confluence uses its own markup format internally; pandoc can convert Confluence HTML exports to reasonably clean Markdown. The conversion quality depends heavily on how complex your Confluence pages are.

For any migration, the practical advice is to migrate the documents that are actively used first and archive the rest rather than attempting a bulk migration of everything. Most wikis and document collections have a long tail of documents that haven't been accessed in months or years. Migrating only the active content keeps the project manageable and the new HedgeDoc instance uncluttered from day one.

For teams who find that HedgeDoc's per-document model doesn't match their wiki or knowledge base needs — where they want hierarchical collections, access control at the collection level, and full-text search across all documents — consider whether a full wiki platform is a better fit. The Docmost vs Outline comparison covers two self-hosted options that provide the structured knowledge base experience HedgeDoc deliberately avoids, so you can make an informed choice before committing to a migration. And for teams evaluating the remote work tooling stack more broadly, HedgeDoc fits naturally alongside communication and project management tools in a remote work open source stack.

Related Guides

For teams building out a complete self-hosted infrastructure stack alongside HedgeDoc, these guides cover the essential operational components:

• Automated Server Backups with Restic and Rclone 2026 — protect your HedgeDoc database and uploads volume with encrypted, deduplicated off-site backups
• How to Self-Host Headscale (Tailscale VPN) 2026 — put HedgeDoc behind a WireGuard mesh network so it is only accessible from authorized devices, not the public internet
• How to Self-Host Prometheus and Grafana Metrics Dashboards 2026 — monitor HedgeDoc's resource usage, track active users and request rates, and set up alerts for container health

---

See all open source productivity tools at OSSAlt.com/categories/productivity.