HedgeDoc: The Collaborative Markdown Editor That Owns Your Meeting Notes — and the AGPL Fine Print You Should Read

HedgeDoc: The Collaborative Markdown Editor That Owns Your Meeting Notes — and the AGPL Fine Print You Should Read

HedgeDoc is the open-source answer to a very specific problem: your team's meeting notes, incident runbooks, and draft RFCs are currently living in a vendor's database, and every time someone says "let me drop a doc link," that link points at infrastructure you do not control. HedgeDoc is a real-time collaborative Markdown editor — share a URL, and everyone with the link is typing in the same document, with live cursors and changes appearing keystroke by keystroke. At roughly 7,400 GitHub stars, it is not the biggest self-hosted editor, but it is one of the few that is unapologetically Markdown-first, AGPL-3.0, and light enough to run on a Raspberry Pi.

The lineage matters. HedgeDoc began as a community fork of CodiMD, which itself was a fork of HackMD's open-source edition. The fork happened precisely because the community wanted to guarantee the codebase stayed fully open and community-driven rather than drifting toward a hosted-product roadmap. That heritage is the reason HedgeDoc feels different from Notion-style block editors: it is plain-text Markdown with a live preview, not a proprietary binary document format. Your notes are files with a syntax, not rows in someone's schema.

But "open source" here carries the obligations AGPL always carries, and the project carries a maintenance story you need to hear before you deploy. HedgeDoc 2 — a complete rewrite — has been in alpha for years, and the 1.x line is explicitly maintenance-only. This review explains what HedgeDoc actually is, how the real-time engine works, what the storage and auth picture looks like, what it honestly costs to run, where your data goes, how it compares to Etherpad and the other wikis in this series, and the one license clause that activates the moment you offer HedgeDoc as a service to others.

HedgeDoc collaborative editing

1. What HedgeDoc Actually Is



HedgeDoc is a web-based, real-time collaborative Markdown editor. You open it in a browser, you write Markdown, and other people with the note's link see your text appear as you type. The interface offers three modes: a raw Markdown editor, a rendered preview, and a side-by-side split that shows both at once. There is no desktop app to install and no client to sync — the editor is the server, and the server is a Node.js application talking to a database.

The job HedgeDoc takes is "the shared scratchpad." Meeting minutes, incident timelines, draft specifications, onboarding checklists, lecture notes — the ephemeral-but-important documents a team produces faster than it files them. For these, a heavyweight wiki with page trees and access-control hierarchies is overkill; what you want is a URL you can paste into a chat and have three people editing within ten seconds. HedgeDoc is built exactly for that shape of work, and it does not pretend to be more.

What it deliberately is not: a knowledge-base platform with nested page hierarchies, a kanban board, or a relational database app. If you need a persistent, structured wiki, that is BookStack or Wiki.js (both covered elsewhere in this series). HedgeDoc is the fast, shared, disposable-to-durable note — and the discipline to copy the good ones into a real wiki afterward is on you.

2. The CodiMD and HackMD Lineage



To understand HedgeDoc you have to understand where it came from, because the lineage is the entire reason the project exists. HackMD was a collaborative Markdown service. It open-sourced its engine, which became CodiMD — a self-hostable version. Over time the community felt CodiMD's governance and roadmap were drifting, and in 2020 the HedgeDoc fork was created to keep the code firmly open and community-run.

This history matters for two reasons. First, it explains the design philosophy: HedgeDoc optimizes for Markdown purity and keyboard-first editing, not for feature breadth. Second, it explains the bus factor and governance reality. HedgeDoc is a community project with a small core team, not a venture-backed company with a support contract. That is generally a good thing for sovereignty, but it means release cadence and the pace of the 2.0 rewrite depend on volunteer time.

The practical takeaway: when you self-host HedgeDoc, you are standing on a fork that was created to protect openness. That is the most sovereign pedigree you can ask for in this category — but it also means you should not expect enterprise SLAs or a sales engineer.

3. The Real-Time Engine: Operational Transform, Not CRDT



The magic of collaborative editing is that two people typing in the same paragraph do not destroy each other's work. HedgeDoc achieves this with operational transform (OT), the same family of algorithm Google Docs uses, rather than a CRDT (conflict-free replicated data type) like Yjs. OT works by transforming incoming operations against a server-authoritative document state, so the server is the referee and clients send edits, not full state.

This is a deliberate choice with trade-offs. OT tends to be simpler to reason about for a central-server model and is battle-tested at scale, but it makes true offline-first editing harder — the server is the source of truth, so a disconnected client cannot merge cleanly later without the server. CRDTs, by contrast, let every replica converge without a referee. HedgeDoc's OT approach fits its "one server, many browsers" deployment and keeps the complexity server-side.

For the operator, the implication is that the backend (the realtime component) must be running and reachable for collaboration to work. If you deploy only the web frontend without the collaboration backend, you get a single-user Markdown editor, not HedgeDoc. That backend is part of the container story below.

4. Markdown That Draws and Computes



Where HedgeDoc earns its keep is the extended Markdown dialect. Out of the box it renders Mermaid diagrams, Graphviz, and Vega-Lite charts, MathJax for equations, syntax-highlighted code blocks in 100+ languages, and embedded content from external sources. Architecture diagrams, equation-heavy specs, and charts live in the same plain-text note as the prose around them.

For technical teams this is a genuine superpower. An incident runbook can embed a Mermaid sequence diagram of the failure path. A design doc can show a Vega-Lite chart of the metric that triggered the discussion. A lecture note can render the derivation inline with MathJax. None of this requires plugins or a build step — it is part of the core renderer.

The cost is portability. Notes that lean heavily on Mermaid or Vega-Lite will not render in a vanilla Markdown viewer; they are HedgeDoc-Markdown, not strictly CommonMark. For a team that lives in HedgeDoc this is a feature, but it is worth naming if you ever plan to bulk-export notes into a different system. The raw text remains readable; the diagrams just become fenced code blocks in a foreign dialect.

5. Presentation Mode: Notes to Slides in One Header



HedgeDoc includes a presentation mode powered by reveal.js. A single YAML frontmatter header and --- slide separators turn any document into a slide deck you present straight from the editor. For teams that already write talk outlines in Markdown, this removes the "now re-type this into slides" step entirely.

This is more than a party trick. Engineering demos, internal tech talks, and sprint reviews often start as a Markdown outline anyway; presentation mode collapses the outline and the deck into one artifact. The same file is the speaker notes and the slides, which means the deck never drifts from the written record.

The honest limitation is that reveal.js theming and advanced transitions are constrained by what HedgeDoc exposes. If you need brand-perfect decks with custom animations, you will still want a dedicated tool. For "stand up and present the runbook" or "walk through the RFC," it is exactly right.

HedgeDoc diagrams and slides

6. The Permission Model: Per-Note Dropdowns



HedgeDoc controls access at the level of the individual note through a simple dropdown: freely editable by anyone with the link, editable only by signed-in users, or locked read-only for published distribution. There is no complex workspace or folder ACL system — the unit of sharing is the note, and the settings are three options.

This is refreshingly simple for ad-hoc collaboration and frustrating for hierarchical governance. If your organization needs "this team sees these notes, that team sees those," HedgeDoc's per-note model pushes that responsibility onto you: you manage who has the link, not who has the role. For public-by-default meeting notes this is fine; for confidential HR or finance docs it is a process problem, not a technical one.

Published notes become clean, read-only web pages — a lightweight "internal blog" or changelog surface. Combined with the revision history below, this makes HedgeDoc viable as a low-ceremony publishing tool, not just a scratchpad.

7. Revision History and the Ability to Revert



Every change to a note is tracked as a revision, and you can view the history and revert to any earlier version with a click. This is the safety net that distinguishes a collaborative editor from a shared textarea: if someone pastes over the whole spec, you do not scramble to reconstruct it, you roll back.

The caveat is storage and retention. Revision history grows with the note, and while HedgeDoc manages it, a heavily edited note accumulates many revisions. There is no built-in pruning of old revisions short of database maintenance, so on a long-lived instance the history tables deserve the same backup attention as the notes themselves.

For audit-minded teams, note that revision history is a record of edits, not of identity-rich attribution beyond what auth provides. If you need "who changed what, when, with sign-off," that lives upstream in your authentication layer and in how disciplined your users are about signing in.

8. Storage Backends: Postgres, MySQL, or SQLite



HedgeDoc supports three database backends: PostgreSQL, MySQL, and SQLite. The choice is a real architectural decision, not a config afterthought. PostgreSQL is the most tested and the one most production guides assume. MySQL works. SQLite is the lightest — it is what lets HedgeDoc run on a Raspberry Pi with essentially zero database administration.

The honest trade: SQLite is single-file and wonderfully simple, but it is the wrong choice the moment you have concurrent writers at scale or you want easy replication and backup tooling. Postgres gives you pg_dump, streaming replicas, and mature backup ecosystems; SQLite gives you a file you copy. For a homelab or a small team, SQLite is genuinely fine. For an organization, Postgres is the responsible default, and the operational cost is "you are now running a Postgres instance," which is a cost this series keeps flagging across every tool.

Crucially, media uploads (images pasted into notes) also need a home: local filesystem, S3, Azure Blob, or Imgur. Local filesystem is simplest; S3/Azure match an existing cloud footprint; Imgur externalizes the bytes off your server entirely, which is a data-sovereignty decision, not a convenience one.

9. Authentication: LDAP, SAML, OAuth2, and Email



HedgeDoc authenticates through local email accounts, LDAP, SAML, and OAuth2. That range covers most organizational identity setups: an email/password realm for small teams, LDAP for the Active Directory shop, SAML for the enterprise IdP, and OAuth2 for the Google/GitHub-identity crowd.

The fine print is version- and config-dependent. SAML and OAuth2 support has matured over the 1.x line but has shipped with bugs that the release notes call out explicitly (attribute mapping fixes, login-flow patches). If your auth integration is mission-critical, read the changelog for the specific version you deploy rather than assuming the latest is flawless.

There is also a "guest" mode: notes can be edited by anyone with the link without an account, which is the entire point of the friction-free scratchpad use case. The tension — easy anonymous collaboration versus controlled identity — is resolved per note, and the server-wide default (allow guests or not) is an admin setting you should set deliberately, not leave at whatever the image shipped.

10. The Docker Story: Four Containers, Not One



A production-grade HedgeDoc deployment is typically four containers: the web frontend, the backend/realtime service, the database, and often a reverse proxy. This is heavier than the "one container and done" pitch the homepage implies, because the collaboration backend is a separate process and the database is a separate concern.

The operational reality: you are orchestrating a small stack. Docker Compose is the common path, with the official images handling web and backend, your database of choice as a third container, and Caddy or Traefik (both covered in this series) in front for TLS. Each container is independently upgradable, which is good for safety and annoying for "I just wanted to take notes."

For a homelab that already runs Postgres and a reverse proxy, HedgeDoc slots in with two new containers. For someone starting from zero, budget an afternoon for the first clean deploy and a recurring few minutes per upgrade. This is not a knock on HedgeDoc; it is the honest shape of any multi-service web app, and naming it up front prevents the "why is this four things" surprise.

HedgeDoc container deployment

11. Hardware Footprint: Yes, a Raspberry Pi



HedgeDoc's light resource profile is real and worth stating, because not every collaborative tool can say it. The 1.x line is documented to run on a Raspberry Pi, and community reports confirm modest RAM and CPU usage for small teams. The SQLite backend removes the database-administration tax entirely on such hardware.

The asterisk is concurrency and media. A Pi is fine for a handful of editors and text notes; it will struggle if you regularly paste large images, run heavy diagram rendering for many users simultaneously, or serve a large organization. The "runs on a Pi" claim is true at the scale it is claimed for and false at scales it is not — the same honesty that applies to every self-hosted tool.

For most readers, the practical bar is "a small VPS or an existing homelab node," not dedicated hardware. HedgeDoc will not be the thing that forces you to buy a server.

12. HedgeDoc 2: The Rewrite That Has Not Landed



The single most important context for a new HedgeDoc operator is the state of HedgeDoc 2. Version 2 is a complete rewrite — backend and frontend separated, modernized stack, new architecture — and it has been in alpha since 2023 with no stable release as of late 2026. The project's own words: 1.x is "maintenance-only," no new features, and they "may choose to close non-critical bug reports" if the bug will not exist in 2.0.

What this means for you: deploy 1.x. It is stable, used around the world, and the only line you should run in production. Treat 2.0-alpha as a curiosity you can try in a throwaway container, not a target. The risk is not that 1.x is broken — it is actively patched, including security fixes through 2026 — but that the future direction is uncertain and the rewrite's timeline has historically slipped.

The strategic implication: if you depend on HedgeDoc long-term, you are betting on a volunteer team finishing a multi-year rewrite. That bet has paid off for many years of 1.x stability; the 2.0 question is simply one you should hold in the back of your mind when choosing where mission-critical docs live.

13. The AGPL-3.0 License and the Network Clause



HedgeDoc is licensed AGPL-3.0. For a self-hosted user this is mostly invisible: you can run it, modify it, and never pay or publish anything. The clause that activates is the one every AGPL carries — if you modify HedgeDoc and offer it as a network service to others, you must make your modified source available to those users.

This is exactly the license that protects you as a user: it closes the "open core with a hosted trap" loophole that plain GPL leaves open for SaaS. HedgeDoc cannot become a proprietary hosted product built on your contributions without those contributions staying open. For a sovereignty-minded operator, AGPL is the strongest available commitment that the tool will not quietly become something you cannot audit.

The obligation only bites if you are the one offering a modified HedgeDoc as a service. Run it unmodified for your team and the AGPL asks nothing of you beyond what any free license does. Name this clearly so nobody on your team fears "we can't use this at work" — you can, and the license is on your side.

14. Honest Limitations: What HedgeDoc Does Not Do



Every tool in this series earns its place by stating what it is not, and HedgeDoc is no exception. It has no native page-tree or nested-folder knowledge base; notes are flat with optional tags. It has no built-in real-time chat or inline comments alongside the document (Etherpad has both; HedgeDoc does not). It is Markdown-first, so non-technical users who expect a Word-like WYSIWYG will find the learning curve real.

Mobile editing works but is not its strength; the split-pane editor assumes a real screen. There is no offline-first mode, because the OT engine is server-authoritative. And heavy diagram or math rendering is CPU on the server, not the client, so a busy instance spends cycles rendering other people's Mermaid.

None of these are defects so much as scope. HedgeDoc is a collaborative Markdown editor, and it guards that scope tightly. The mistake is deploying it expecting a wiki, a chat, or a mobile-first app — it is none of those, and pretending otherwise produces disappointment the project never promised to prevent.

15. The Real Cost of Running HedgeDoc



Let us put numbers on it. A small team deployment on a VPS: a 2 vCPU / 4 GB RAM instance (shared with other small services, or dedicated at ~$10–15/month) covers web, backend, and a Postgres container comfortably for dozens of users. Storage is trivial for text — call it a few hundred MB to a few GB including revisions and uploaded images. The database is your largest recurring cost if you run Postgres just for this; co-locating with an existing instance is the frugal move.

The cost that is not on the invoice is time. Initial deploy: an afternoon. Upgrades: a few minutes per release, more if a config variable changed. Backups: a pg_dump cron plus copying the uploads directory. Monitoring: it is a web app, so you want uptime checks (Uptime Kuma, covered in this series) and log scrutiny.

Compared to a hosted notes product, the hard-dollar saving is real if you already own the server; the soft cost is that you are now the ops team. For a team that already self-hosts, HedgeDoc adds one small stack to an existing habit. For a team that does not, the true price is acquiring the self-hosting competence, not the software license, which is free.

16. Where Your Data Goes (and Does Not)



Data sovereignty is the entire reason to run HedgeDoc, so state it plainly: your notes, revisions, and (with local or S3/Azure storage) your uploaded media live on infrastructure you control. There is no HedgeDoc cloud phoning home, no analytics endpoint shipping your prose to a vendor, no "we improved our model using your documents" clause, because there is no vendor in the loop. The AGPL guarantees the code cannot acquire one without you seeing it.

The one externalization decision is media upload backend. If you choose Imgur, your images leave your server and live on Imgur's infrastructure — a convenience that trades sovereignty for simplicity. Choose local filesystem or your own S3/Azure bucket to keep every byte in-house. That single setting is the difference between "fully sovereign" and "sovereign except the pictures."

For regulated or confidential content, the corollary is that sovereignty is only as strong as your backup and access-control discipline. HedgeDoc puts the data in your hands; what you do with that custody — encryption at rest, offsite backups, guest-link policy — is the part no license can do for you.

HedgeDoc data sovereignty

17. HedgeDoc vs Etherpad vs the Wikis



The honest comparison set is three tools, not one. Against Etherpad (Apache-2.0, rich-text WYSIWYG), HedgeDoc wins if your team writes Markdown and wants built-in diagrams, math, and slide mode; Etherpad wins for non-technical users, a 1,000+ plugin ecosystem, and inline chat/comments. Both are real-time; they target different authors.

Against BookStack (MIT, no real-time collaboration) and Wiki.js (AGPL, Git-backed), HedgeDoc is the ephemeral collaborator, not the persistent library. BookStack's rigid shelf/book/chapter/page hierarchy is for curated knowledge; Wiki.js's Git backend is for docs-as-code. HedgeDoc's flat notes are for the live session. The right answer is often to run HedgeDoc for the meeting and copy the durable outcome into BookStack or Wiki.js afterward.

The license contrast is itself informative: Etherpad is permissive Apache-2.0, BookStack is permissive MIT, Wiki.js and HedgeDoc are copyleft AGPL-3.0. If "no copyleft" is a hard requirement, HedgeDoc is out and Etherpad or BookStack fit; if "strongest user protection" matters more, AGPL is the point.

18. Security Posture: Patches Are Frequent for a Reason



Collaborative editors are attack surface — they accept untrusted input (your collaborators' text, uploaded images, external links) and render it. HedgeDoc's 2026 changelog shows this plainly: 1.11.0 addressed four vulnerabilities (HTML injection, DoS, CSRF, rate-limiting bypass); 1.11.1 added security fixes for permission validation; 1.10.6 closed SVG script execution. These are not signs of a broken project; they are signs of one that audits and patches.

The operational lesson is that you must keep current. Running an old HedgeDoc with known CVEs is running an exposed input renderer on your network. The maintenance-only 1.x line still ships security fixes, so staying patched is a matter of discipline, not availability. Pin a version, watch the releases, and update on security advisories — the same rhythm every internet-facing app demands.

One more: SVG uploads can execute scripts in some contexts, which is exactly why the project patches them repeatedly. If you do not need SVG paste, consider restricting upload types in config. Sovereign does not mean permissive by default; it means you hold the switch.

19. Backup and Disaster Recovery



Backing up HedgeDoc is backing up its database plus its media store. For Postgres, a scheduled pg_dump to an offsite location is the core. For SQLite, copy the database file (ideally while the service is stopped or via a clean snapshot) plus the uploads directory. For S3/Azure media, your bucket's own backup covers the images.

The revision history lives in the same database as the notes, so a single pg_dump captures both — good. The failure mode is forgetting the uploads directory when using local storage: the notes restore, the pasted screenshots do not. Make the backup job cover both atoms or you will discover the gap during the restore you are trying to survive.

Test the restore. A dump you have never restored is a hope, not a backup. Spin up a scratch instance, load the dump, confirm a known note and its revisions appear, and only then trust the pipeline. This is the most-skipped step in self-hosting and the most expensive to skip.

20. Upgrading Without Breaking the Room



HedgeDoc upgrades are generally smooth within the 1.x line — pull new images, recreate containers, and the database migrations run on startup. The discipline that prevents pain is reading the release notes for breaking changes: auth attribute mappings, upload config options, and Node version requirements (1.12.0 bumped the floor to Node 20.17+) have all changed and bitten the unwary.

Because the realtime backend and web frontend are separate containers, mismatch between them during a partial rollout can cause collaboration glitches. Upgrade them together, not one at a time, and keep a known-good compose file in version control so a bad deploy is a git revert away.

The 2.0 question returns here: do not attempt to migrate 1.x to 2.0-alpha in production. When 2.0 stabilizes, expect a deliberate, documented migration path; until then, treat 1.x as the permanent home and plan exits (export to Markdown) rather than upgrades.

21. Who Should Run HedgeDoc — and Who Should Not



Run HedgeDoc if your team lives in Markdown, needs friction-free shared notes, and values owning the data over having a polished proprietary feature set. Developers, DevOps, technical writers, researchers, and educators are the natural fit. If you already self-host, it is a small, well-behaved addition.

Do not run it if you need a governed knowledge base with role-based hierarchies (use BookStack or Wiki.js), a WYSIWYG editor for non-technical staff (use Etherpad or a block editor), or a mobile-first offline app. And be honest with yourself about the 2.0 uncertainty: if you require a roadmap with SLAs, a volunteer-maintained tool with a multi-year rewrite is a risk you should weigh, not ignore.

The aggregate verdict is a strong yes for the right team and a clear no for the wrong use case. HedgeDoc is not trying to be everything; it is trying to be the best sovereign collaborative Markdown editor, and on that narrow job it delivers.

22. API, Automation, and Embedding



HedgeDoc exposes a REST API that lets you create, read, update, and manage notes programmatically, which is what turns it from a human scratchpad into a building block. A common pattern is a bot or CI job that drafts a note from a template — an incident postmortem stub, a standup agenda, a release checklist — and posts the link into chat before the meeting starts. Because notes are plain Markdown, generating them from code is trivial, and the API handles permissions and history like the UI does.

Embedding is the other integration axis. Published notes can be embedded as read-only iframes in a wiki, a dashboard, or an internal portal, so the "live doc" and the "published view" share one source. For teams that already run BookStack or Wiki.js, embedding HedgeDoc notes inside them is a pragmatic way to get real-time collaboration without migrating your whole knowledge base.

The caveat is the same as every API surface: it is an attack and leakage vector. An API token with write access is a writable entry point to your notes, so scope tokens narrowly, rotate them, and never embed them in client-side code. Sovereign also means accountable, and an unmonitored API key is the opposite of accountable.

23. Troubleshooting the Rooms That Will Not Sync



The failure you will actually hit is "two people are editing but changes are not appearing." Nine times out of ten this is the realtime backend not being reachable — the web container can serve pages while the collaboration service is down or misconfigured, leaving you with a single-user editor that looks collaborative until two people try. Check that the backend container is up, that the web container points at it, and that no firewall or proxy is blocking the websocket or long-poll path.

The second common failure is media uploads failing silently — a note saves but the pasted image does not appear. This is almost always the upload backend misconfiguration (wrong S3 credentials, unwritable local path, or Imgur rate limits). Test uploads with a small image right after deploy; do not discover the gap during a live session.

The third is auth lockout: a broken SAML/OAuth mapping that prevents anyone from signing in. Keep a local admin account enabled as a break-glass, and validate auth in a private window before flipping the setting that disables guest access. Every one of these is recoverable from the server; none requires a vendor, which is the whole point.

24. Mobile and the Offline Gap



HedgeDoc is fundamentally a browser app designed for a real screen and a live connection, and the mobile story reflects that. You can open and edit notes from a phone browser, but the split-pane editor and diagram-heavy workflow assume desktop-class space. For "check the runbook on the train," it is adequate; for "write the spec on a phone," it is not the tool's strength.

The offline gap is the sharper edge. Because the real-time engine is server-authoritative (operational transform, not a CRDT), a disconnected client cannot keep editing and silently merge later the way a CRDT-based app would. Lose the connection and you lose live collaboration; your in-flight keystrokes are buffered, not converged. For most note-taking this is irrelevant — you are usually online — but if your use case is field work, travel, or flaky connectivity, name this limitation before you commit, because it is a property of the sync model, not a bug to be patched.

25. The Bottom Line



HedgeDoc is a focused, AGPL-3.0, Markdown-first collaborative editor with a clean pedigree (a fork created to protect openness), a real operational-transform engine, and diagrams-plus-slides that technical teams actually use. It runs on modest hardware, supports serious auth, and keeps your notes on your infrastructure with no vendor in the loop. The honest caveats — flat note model, no chat/comments, server-authoritative editing, a 2.0 rewrite still in alpha, and AGPL obligations only if you resell a modified service — are scope statements, not defects.

If your team's institutional memory is currently scattered across a hosted vendor's database, HedgeDoc is a credible, low-cost way to bring the live, collaborative part back home. Pair it with BookStack or Wiki.js for the durable library, back it up like the production app it is, keep it patched, and the meeting notes stop leaving your control the moment someone pastes the link.



Related



For the rest of a sovereign, self-hosted stack, these pieces from our series travel with HedgeDoc:

Comments (0)

No comments yet. Be the first to comment!

Leave a Comment