# HedgeDoc: self-hosted real-time collaborative markdown, and the 1.x to 2.x fork in the road

> HedgeDoc is an AGPL-3.0, TypeScript markdown editor for real-time collaboration, installable via Docker or from source. The develop branch is the in-progress HedgeDoc 2 rewrite; the stable 1.x line is maintenance-only, and that split is the first thing to settle before you deploy anything.

**hedgedoc/hedgedoc** — HedgeDoc - Ideas grow better together

- Repository: https://github.com/hedgedoc/hedgedoc
- Website: https://hedgedoc.org
- Stars: 7,452 · Forks: 601
- Language: TypeScript
- License: AGPL-3.0
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/hedgedoc-hedgedoc

## What HedgeDoc is for, and who actually needs it

HedgeDoc lets you create real-time collaborative markdown notes. That one sentence from the README is the whole product thesis: several people, one markdown document, edits appearing live. The audience is teams that already think in markdown and want a shared surface for it, without routing every note through a SaaS account. Meeting minutes, runbooks, specification drafts, conference notes, the working document that six people are editing during a call.

The alternative most of those teams reach for is a general-purpose wiki with a page tree and a rich-text editor. HedgeDoc inverts that. The document is the unit, the editing surface is markdown, and collaboration is the default rather than a mode you enable. If your notes are short, personal and never shared, this is more machinery than the job requires.

The project has a long history, and the README is candid about where it is now. HedgeDoc 1.x is described as stable and used around the world, but the codebase has grown over time, which the project says makes it hard to add new features. That admission shapes everything below.

## The two-branch problem: 1.x maintenance versus the HedgeDoc 2 rewrite

The single most important thing to understand before installing HedgeDoc is that the repository you are reading about is not the stable product. The default branch is develop, and the README states plainly that this branch contains the latest development code and does not implement all features yet. If you want the 1.x source code, the README points you at the master branch instead.

HedgeDoc 2 is a complete rewrite, split into a backend and a frontend, both present in this repository. The top-level layout reflects that: backend/, frontend/, commons/, database/, markdown-it-plugins/, html-to-react/. The root package.json carries version 2.0.0-alpha.3, and the workspace is orchestrated by turbo with pnpm pinned to 11.24.0. That is a monorepo build, not a single application directory.

The stable line is not standing still, but it is not growing either. Releases 1.11.0, 1.11.1 and 1.12.0 arrived between June and August 2026, and the README says the 1.x release is maintenance-only, that feature requests and PRs for it are no longer accepted, and that non-critical bug reports may be closed if the bug will not exist in 2.0. Read that as a contract: you will get fixes, not features, and not every bug report.

So the decision is not "HedgeDoc or something else" first. It is "which HedgeDoc" first, and the two answers have different risk profiles.

## How the backend and frontend are split in HedgeDoc 2

The rewrite separates concerns in a way 1.x did not. The backend is a NestJS application, evidenced by the Nest.JS CI workflow referenced in the README badges, and it listens on its own port. The frontend is a separate build. A reverse proxy sits in front of both, and the repository ships a dev-reverse-proxy/ directory for exactly that purpose during development.

Configuration is environment-variable driven, and .env.example lists the variables rather than the defaults. Note the file's own warning: it says the example just lists all available environment variables and does not represent the default settings of HedgeDoc. Two URL variables matter for routing. HD_BASE_URL is the public address users hit, shown as http://localhost:8080 in the example. HD_RENDERER_BASE_URL is a separate variable, also shown as http://localhost:8080. HD_BACKEND_PORT is 3000 in the example, so the backend and the public URL are deliberately different ports behind the proxy.

Authentication is pluggable rather than fixed. The example file shows a local account system (HD_AUTH_LOCAL_ENABLE_LOGIN, HD_AUTH_LOCAL_ENABLE_REGISTER), LDAP with per-server prefixed keys such as HD_AUTH_LDAP_MYLDAP_URL and HD_AUTH_LDAP_MYLDAP_SEARCH_FILTER, and OIDC providers declared through HD_AUTH_OIDC_PROVIDERS. A single HD_AUTH_SYNC_SOURCE selects which one is authoritative. Sessions are signed with HD_AUTH_SESSION_SECRET, whose example value is literally change-me-in-production, and expire after HD_AUTH_SESSION_LIFETIME seconds.

That design is flexible and it is also the main source of configuration mistakes, because provider-specific keys are namespaced by the provider name you invent yourself.

## Installing HedgeDoc and opening your first collaborative note

The README does not put install commands inline. It points at the install guide at docs.hedgedoc.org/setup/getting-started/ for self-hosting, and at docs.hedgedoc.dev for trying HedgeDoc 2 on your own devices, with the caveat that those docs may change over time. A docker/ directory exists at the repository root, which is where container assets live. Because the README gives no literal docker run or compose command, none is reproduced here.

What the repository does give is the configuration surface. Copy .env.example to a working file and edit it. The variables below are taken verbatim from that file, with the example values it shows.

```bash
HD_BASE_URL=http://localhost:8080
HD_RENDERER_BASE_URL=http://localhost:8080
HD_BACKEND_PORT=3000
HD_LOG_LEVEL=info
HD_AUTH_SESSION_SECRET=change-me-in-production
HD_AUTH_LOCAL_ENABLE_LOGIN=true
HD_AUTH_LOCAL_ENABLE_REGISTER=true
```

Two of those deserve attention before you start anything. HD_AUTH_SESSION_SECRET must be replaced with a real secret; the example value is a placeholder. And HD_AUTH_LOCAL_ENABLE_REGISTER=true means anyone who can reach the instance can create an account, so decide deliberately whether that is what you want on a public URL.

For local development of the rewrite, the root package.json defines the scripts. The toolchain is pnpm 11.24.0 with turbo, and dotenv-cli loads the environment per mode.

```bash
pnpm install
pnpm run start:dev
```

The start:dev script runs dotenv -c development -- turbo run start:dev, so it loads the development environment and starts the workspace tasks. The README directs developers to docs.hedgedoc.dev/how-to/develop/setup/ for the full local setup, which is the authoritative source for prerequisites and database configuration; the repository layout alone does not tell you what the backend expects to connect to.

There is also a demo instance linked from the README at hedgedoc.org/demo, and an alpha demo of HedgeDoc 2 at hedgedoc.dev. Trying those first costs nothing and tells you more about the editing experience than any configuration file.

## Where HedgeDoc is the wrong tool

HedgeDoc is a document editor, not a knowledge base. It has no page hierarchy, no backlinks, no folder tree in the sense a wiki gives you. If your team's problem is "we cannot find the note from six months ago", a collaborative editor makes that problem slightly worse, because the easy path is another link in a chat thread.

The 1.x maintenance policy is a real constraint, not a footnote. The README states that feature requests and PRs for 1.x are no longer accepted. If you deploy 1.x and your team later asks for a capability that only exists in 2.0, the answer is a migration, not a setting. Conversely, deploying the develop branch means deploying 2.0.0-alpha.3, and the README says that branch does not implement all features yet. Neither branch is a comfortable middle.

The documentation is also thin in places that matter operationally. The README does not document rollback, and it does not document how to export your documents out of an instance. Those are the two questions to answer before you migrate a team onto it, and the repository's own files do not answer them. For a single person keeping private markdown notes, a plain local editor is less work than running a NestJS backend, a frontend, a database and a reverse proxy.

## HedgeDoc compared with Etherpad and Outline

Etherpad and Outline come up as alternatives, and they fail in different directions, which makes the comparison useful.

Etherpad is a real-time collaborative text editor first. It is built around simultaneous editing of a plain document, with no markdown-first authoring model and no notion of a markdown note as the artifact. HedgeDoc's difference is that the collaborative surface and the markdown source are the same thing: what people edit together is markdown, and the README frames the product as markdown notes specifically. If your output needs to be a markdown file you can commit somewhere, HedgeDoc is closer to that than Etherpad is. If you want the lowest-friction simultaneous typing surface and the format is irrelevant, Etherpad's model is simpler.

Outline is a wiki. It gives you collections, a document tree, search across an organization and a permissions model built for a company knowledge base. That is the structure HedgeDoc deliberately does not have. The trade is inverted: Outline asks you to think about where a document belongs and who can see it, and HedgeDoc asks you to think about the document itself. Teams that adopt HedgeDoc and then try to reconstruct a wiki out of link conventions are usually the teams that should have picked Outline.

One more distinction worth stating, since it appears in search data: HedgeDoc versus CodiMD. CodiMD is the project's former name, so this is a lineage question rather than a feature comparison, and the README's link to the project history page is the place to read that story.

## Licence, upgrade cost and what to check before you commit

HedgeDoc is licensed under AGPL-3.0, as stated in the README and in the LICENSE file. The AGPL's network clause is the part that matters for self-hosters: if you modify the software and let users interact with it over a network, the licence's source-availability obligations apply. Running an unmodified instance for internal use is the ordinary case and is what most deployments do. This is not legal advice; if you plan to modify and expose HedgeDoc, talk to someone qualified.

One carve-out is stated explicitly. The README says the licence does not include the HedgeDoc logo, whose terms live in a separate repository. If you fork or rebrand, the logo is not yours to reuse under AGPL-3.0.

The upgrade cost depends entirely on which branch you chose. On 1.x, releases arrive on a rough monthly cadence based on the recent tags, and the changes are fixes rather than features, so upgrades are small but the ceiling is fixed. On the 2.x develop branch, you are tracking an alpha whose documentation the README itself says may change over time, and the monorepo layout means backend and frontend move together.

The repository is not archived, and the last push was on 2026-09-21, so development activity is current. That says nothing about whether the branch you want is finished. Before deploying, decide which branch you are on, replace HD_AUTH_SESSION_SECRET, decide whether HD_AUTH_LOCAL_ENABLE_REGISTER should be true, and confirm where your data lives, since the README does not cover export or rollback.

## Conclusion

Adopt HedgeDoc if you want markdown notes that several people can edit at once on hardware you control, and you are willing to accept that the stable 1.x line is maintenance-only while HedgeDoc 2 is still an alpha. Do not adopt it if you need a stable, feature-frozen collaborative editor with a documented upgrade path today, or if your team lives inside a wiki product with page hierarchies and a permissions model rather than in markdown documents. Before you commit, verify three things: which branch you are actually deploying (the develop branch README warns it does not implement all features yet), where your documents are stored, and how you will get them out again, because the README documents neither rollback nor export.

## FAQ

### What is HedgeDoc?

HedgeDoc is a self-hostable editor for real-time collaborative markdown notes, written primarily in TypeScript and licensed under AGPL-3.0. The README describes it as letting you create real-time collaborative markdown notes, and points to a hosted demo instance for trying it out.

### How do I install HedgeDoc?

The README does not give install commands inline; it directs you to the install guide at docs.hedgedoc.org/setup/getting-started/ for self-hosting, and the repository contains a docker/ directory with container assets. For the HedgeDoc 2 alpha, the README points to docs.hedgedoc.dev, warning that those docs may change over time.

### How do I use HedgeDoc?

You create and edit markdown documents that other people can edit at the same time. To run it yourself you configure the instance through environment variables such as HD_BASE_URL, HD_BACKEND_PORT and HD_AUTH_SESSION_SECRET, which are listed in .env.example, then start the backend and frontend behind a reverse proxy.

### Is HedgeDoc free?

Yes. HedgeDoc is licensed under AGPL-3.0, so you can self-host it without paying for the software. The README notes that the licence does not cover the HedgeDoc logo, which has separate usage terms in its own repository.

### What is the difference between HedgeDoc and CodiMD?

CodiMD is the project's former name, so this is a question about the project's own history rather than a comparison between two separate tools. The README links to the project history page on hedgedoc.org for that background.

## Sources

- [hedgedoc/hedgedoc on GitHub](https://github.com/hedgedoc/hedgedoc)
- [License: AGPL-3.0](https://github.com/hedgedoc/hedgedoc/blob/develop/LICENSE)
- [Project website](https://hedgedoc.org)
- [README](https://github.com/hedgedoc/hedgedoc/blob/develop/README.md)
- [Releases](https://github.com/hedgedoc/hedgedoc/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hedgedoc-hedgedoc