HedgeDoc

HedgeDoc is a self‑hosted, web‑based collaborative Markdown editor that scales from single‑user notes to multi‑tenant team spaces. At its core, it implements real‑time synchronization using Operational Transformation (OT) and WebSocket transport, allowing dozens of users to edit the same document with low latency. The platform exposes a RESTful API for CRUD operations on notes, user management, and permission handling, while also offering Webhooks to integrate with external CI/CD pipelines or messaging systems.

Technical Stack

• Backend: Built on NestJS (a progressive Node.js framework) leveraging TypeScript, Express, and GraphQL for flexible query patterns. The core logic is split into modular services (AuthService, NoteService, CollaborationService) that interact with a PostgreSQL database via TypeORM.
• Realtime Engine: Uses the ot library for Operational Transformation and a custom WebSocket gateway (NestJS’s WebSocketGateway) to broadcast changes. Session state is persisted in Redis for horizontal scaling.
• Frontend: A Vue 3 single‑page application (SPA) that consumes the REST/GraphQL API. The editor itself is powered by CodeMirror 6, enriched with Markdown parsing and live preview. Presentation mode is a thin wrapper around Reveal.js, enabling slide decks directly from Markdown.
• Storage: PostgreSQL stores note metadata and revision history. Raw file uploads (images, attachments) are served from a mounted volume or an S3‑compatible bucket via the multer middleware.

Core Capabilities

• Real‑time Collaboration: OT‑based sync with conflict resolution, cursor sharing, and presence indicators.
• Permission System: Fine‑grained access control (read/write/owner) managed through a dropdown UI and exposed via the API.
• Revision History: Immutable snapshots stored in PostgreSQL, with a UI for diffing and reverting.
• Graph & Diagram Support: Integration of Mermaid, PlantUML, and LaTeX rendering engines; diagrams are rendered client‑side via embedded libraries.
• API & Webhooks: Endpoints for creating notes, listing users, and subscribing to note‑change events. Webhooks can be configured per note or globally.

Deployment & Infrastructure

HedgeDoc ships as a Docker image and a pre‑built bundle. The recommended deployment pattern is a Docker Compose stack comprising:

1. hedgedoc – the application container.
2. postgres – PostgreSQL database.
3. redis – in‑memory store for OT state and session data.

For production, a reverse proxy (NGINX or Traefik) is typically added to handle TLS termination and HTTP/2. Horizontal scaling is achieved by running multiple HedgeDoc instances behind a load balancer, sharing the same PostgreSQL and Redis backends. The OT state is sharded across Redis nodes to avoid bottlenecks.

Integration & Extensibility

• Plugins: HedgeDoc exposes a plugin API that allows developers to inject custom commands into the editor toolbar, add new Markdown extensions, or hook into lifecycle events.
• Webhooks: External services can subscribe to note‑change events, enabling automated build triggers or audit logging.
• Custom Themes: The front end supports CSS overrides and custom theme files, making it straightforward to brand the editor for internal tooling.
• OAuth & SSO: Supports OpenID Connect and LDAP authentication out of the box, facilitating integration with corporate identity providers.

Developer Experience

The project follows a clean monorepo structure, with clear separation between backend and frontend directories. Documentation is hosted at docs.hedgedoc.org, covering architecture, API reference, and contribution guidelines. The community is active on Matrix chat rooms (hedgedoc:matrix.org), and the codebase adheres to AGPLv3, ensuring that improvements remain open. Continuous integration pipelines (GitHub Actions) enforce code quality and run unit/integration tests, giving contributors confidence that their changes will not break existing functionality.

Use Cases

• Internal Documentation: Teams can maintain living documentation, slide decks, and flowcharts without leaving the browser.
• Education: Instructors can share live notebooks with students, enabling collaborative coding or note‑taking during lectures.
• Project Planning: Agile teams use HedgeDoc to create and iterate on sprint backlogs, roadmaps, and diagrams.
• Knowledge Base: Small businesses host a self‑contained wiki that remains under their control, with revision history for auditability.

Advantages

• Performance: OT and Redis provide low‑latency collaboration even on modest hardware (e.g., Raspberry Pi).
• Flexibility: The split backend/frontend architecture allows developers to swap out the UI or extend the API without touching core logic.
• Licensing: AGPLv3 guarantees that any derivative work remains open, aligning with many open‑source projects’ policies.
• Community & Support: Active Matrix channels, detailed docs, and a robust CI pipeline reduce onboarding friction.

In summary, HedgeDoc delivers a feature‑rich, low‑footprint collaborative editor that is architected for extensibility and self‑hosted control—making it an attractive choice for developers who need a dependable, customizable knowledge‑sharing platform.