CodiMD — Real-Time Collaborative Markdown Notes

Introduction

CodiMD is an open-source, self-hosted collaborative markdown editor originally forked from HackMD. It allows multiple users to edit markdown documents together in real time with instant preview. It supports diagrams, math equations, and slide presentations within markdown.

What CodiMD Does

• Enables real-time collaborative editing of markdown documents with live cursors
• Renders markdown with support for tables, diagrams, math (KaTeX), and code highlighting
• Provides slide mode to turn markdown documents into presentations
• Supports multiple authentication methods including OAuth, LDAP, and SAML
• Stores documents in a PostgreSQL or MySQL database with revision history

Architecture Overview

CodiMD is a Node.js application using Express for the web server and Socket.IO for real-time collaboration. The operational transformation engine synchronizes edits across connected clients. Documents are stored in a relational database (PostgreSQL or MySQL), and file uploads can be directed to local storage or S3-compatible backends. The frontend uses CodeMirror as the editor component.

Self-Hosting & Configuration

• Deploy with Docker using the official hackmdio/hackmd image and a database container
• Configure the database connection via CMD_DB_URL environment variable
• Set up authentication with environment variables for GitHub, Google, LDAP, or SAML
• Configure file upload storage to local disk, S3, or Azure Blob Storage
• Use a reverse proxy like Nginx for HTTPS termination in production

Key Features

• Real-time collaboration: multiple users edit simultaneously with live sync
• Rich markdown: diagrams (Mermaid), math (KaTeX), and syntax-highlighted code blocks
• Slide mode: convert any document into a reveal.js presentation
• Flexible auth: supports local accounts, OAuth providers, LDAP, and SAML
• Revision history: browse and restore previous versions of any document

Comparison with Similar Tools

• HackMD: the commercial hosted version; CodiMD is the self-hosted open-source fork
• HedgeDoc: a community fork of CodiMD with continued development under a new name
• Etherpad: real-time editor but plain text only; CodiMD provides full markdown rendering
• Outline: wiki-style knowledge base; CodiMD is focused on quick collaborative notes

FAQ

Q: What is the relationship between CodiMD, HackMD, and HedgeDoc? A: HackMD is the commercial product. CodiMD was the open-source self-hosted version. The community later forked CodiMD into HedgeDoc for independent development.

Q: What database backends are supported? A: PostgreSQL, MySQL, MariaDB, and SQLite are all supported.

Q: Can I export documents? A: Yes. Documents can be exported as markdown, HTML, or raw text from the editor interface.

Q: Is there a mobile app? A: There is no dedicated mobile app, but the web editor works in mobile browsers with responsive layout.

Sources

• Repository: https://github.com/hackmdio/codimd
• Documentation: https://hackmd.io/c/codimd-documentation