Jot: The Minimal Markdown Editor for Self-Hosted, Secure Notes

Let’s be honest: you’re drowning in markdown editors. Obsidian’s great—until you need to share notes with your team and suddenly you’re wrestling with sync conflicts, cloud dependencies, and permission matrices. Notion’s slick—but it phones home, and good luck convincing your security team to let it near internal docs. Jot isn’t another bloated SaaS clone. It’s a 220KB static frontend + lightweight Node.js backend that lets you edit .md files in your browser, add inline comments like GitHub PRs, and run the whole thing on a $5/month VPS—or your homelab NAS—with zero external dependencies. As of May 2024, it has 83 GitHub stars, zero sponsors, and absolutely no telemetry. And yes—it actually works.

What Is Jot? A Minimal Markdown Editor With Real Comment Threads

Jot (by Mario Zechner, creator of libGDX and ex-Google engineer) is a refreshingly narrow-scope tool: it serves local markdown files over HTTP, renders them with a clean editor (CodeMirror 6), and adds comment threads anchored to line numbers—just like GitHub. No accounts. No signups. No database. It stores comments in .jot sidecar files right next to your .md files (e.g., meeting-notes.md + meeting-notes.md.jot). The backend is a ~300-line Express server (server.js) that handles file reads/writes, comment CRUD, and basic auth if you enable it.

It’s not a wiki. Not a CMS. Not a knowledge base with search or tagging. It’s a markdown editor + comment layer—period. That constraint is its superpower. I dropped it onto a Raspberry Pi 4 (4GB RAM) running Ubuntu 22.04, pointed it at a shared /srv/jot/docs directory, and gave my team a single URL. Within 20 minutes, they were commenting on RFC drafts inline, not in Slack threads or emailed PDFs.

Here’s the kicker: Jot renders comments live, without page reloads. Click a line → type → hit enter → your comment appears instantly for everyone else viewing that file. No WebSockets—just polling every 3 seconds (configurable), and it feels snappy even over 4G.

Why Self-Host Jot? Who Actually Needs This?

Jot isn’t for everyone. But it is for these people:

• Engineering teams writing RFCs, ADRs, or design docs who want lightweight, Git-compatible collaboration without GitHub/GitLab lock-in
• Remote research groups or academic labs sharing annotated literature reviews or protocol drafts
• Sysadmins documenting internal runbooks, where comments like “⚠️ this broke in kernel 6.8.3” need to stay next to the command
• Privacy-first orgs that block SaaS editors outright (e.g., healthcare, govt contractors)

It’s not for you if you need version history, user roles, search, or mobile apps. Jot doesn’t track who wrote what beyond the comment author field (which is client-set—yes, that’s a footgun, more on that later). It also doesn’t parse frontmatter or render Mermaid—just pure CommonMark + syntax highlighting.

That said: if your workflow is “write .md in VS Code → push to Git → review in browser → comment → commit”, Jot cuts out the middleman. Comments live in your repo (.jot files are plain JSON), so they survive git clone. I ran git add *.jot && git commit -m "comments on API spec" last week—no extra syncing step.

Installation: Docker, Bare Metal, and the 2-Minute Setup

Jot is stupidly easy to deploy. No build step. No migrations. You can run it bare-metal (Node 18+ required), but Docker is the sane choice—especially since it ships with a working Dockerfile.

Docker Compose (Recommended)

Here’s my production-ready docker-compose.yml (tested on Docker 24.0.7, Ubuntu 22.04):

version: '3.8'
services:
  jot:
    image: badlogic/jot:0.10.0
    ports:
      - "8080:3000"
    volumes:
      - /srv/jot/docs:/app/docs
      - /srv/jot/data:/app/data
    environment:
      - JOT_PORT=3000
      - JOT_BASE_URL=/  # Important: trailing slash!
      - JOT_READ_ONLY=false
      - JOT_BASIC_AUTH_USER=admin
      - JOT_BASIC_AUTH_PASS=super-secure-password
    restart: unless-stopped

⚠️ Key notes:

• /app/docs is where your .md files live. Jot serves only from here—no directory traversal.
• /app/data stores session tokens and (if enabled) basic auth salt—keep this persistent.
• JOT_BASE_URL must end with /, or comment anchors break. I lost 45 minutes to this.
• JOT_READ_ONLY=true disables editing but keeps comments working—great for read-only docs portals.

Then run:

mkdir -p /srv/jot/{docs,data}
docker compose up -d

Done. Visit http://your-server:8080, log in, and drop a test.md in /srv/jot/docs. Refresh—and yes, it’s there.

Bare Metal (For Tinkerers)

git clone https://github.com/badlogic/jot.git
cd jot
npm ci  # Uses exact versions from package-lock.json
cp config.example.json config.json
# Edit config.json: set "docsPath" and "dataPath"
npm start

It binds to localhost:3000 by default. Use nginx or caddy in front for HTTPS and auth. I run mine behind Caddy 2.8 with automatic TLS:

jot.internal {
  reverse_proxy http://localhost:3000
  basicauth * {
    admin JDJhJDEwJE1vT0R1U0dUWlJqQ09uZlBmTlRrZ3J5cGhQWk5JZGZUcGd0T2hOQ3ZJY1RmZUJmU1V6T3JjNQo=
  }
}

Jot vs. Alternatives: Why Not Obsidian, Notion, or HackMD?

Let’s compare real-world tradeoffs—not feature checklists.

Here’s where Jot wins in practice:

• Git workflow integrity: Your *.jot files are JSON arrays. You can git diff them, git blame who suggested that breaking change, and git revert a comment thread. Try that with HackMD’s PostgreSQL dump.
• Zero lock-in: Export your docs folder + all .jot files → you have everything. No vendor-specific export format.
• Speed: On my Pi 4, Jot boots in 1.2s. Obsidian takes 8s to load my 200-note vault. HackMD needs 3 containers and 15s to warm up.

Where it loses:

• No search. If you have 500+ docs, you’ll grep -r "error 500" /srv/jot/docs.
• No mobile editing (the UI isn’t responsive—fine for desktop, awkward on tablets).
• No markdown preview toggle. It’s edit or render—no split view.

If you’ve been using HackMD for team docs and hate managing PostgreSQL backups, Jot is a breath of fresh air. If you’re deep in Obsidian and love plugins, Jot will feel like stepping back—but you’ll gain Git-native collaboration.

Configuration, Security, and Real-World Quirks

Jot’s config.json is straightforward—but a few settings trip people up:

{
  "docsPath": "/app/docs",
  "dataPath": "/app/data",
  "port": 3000,
  "readOnly": false,
  "basicAuth": {
    "user": "admin",
    "pass": "super-secure-password"
  },
  "pollIntervalMs": 3000,
  "maxCommentLength": 2000,
  "enableLineNumbers": true
}

• pollIntervalMs: Lower = more real-time, higher = less load. 3000 is sane. I tried 500—no perceptible gain, just more HTTP requests.
• enableLineNumbers: Set to true. Without it, comment anchors don’t align.
• basicAuth: Uses bcrypt under the hood (v0.10.0 uses [email protected]). No OAuth. No SSO. If you need SSO, proxy through Authelia or nginx-auth-pam.

Security-wise: Jot has no known CVEs (as of May 2024) and hasn’t had a security audit—but its attack surface is tiny. It doesn’t execute code, doesn’t parse YAML/JSON input (comments are validated as strings), and doesn’t allow file uploads. The biggest risk? A misconfigured docsPath that exposes /etc/passwd. Jot does validate paths—../etc/passwd gets rejected with 403—but test it.

Hardware-wise:

• Minimum: Raspberry Pi 3 (1GB RAM), 10GB storage
• Recommended for 10+ users: 2 vCPU, 2GB RAM, SSD (for faster .jot file I/O)
• RAM usage: 45–65MB idle, peaks at 90MB during heavy commenting (tested with 8 concurrent users on a t3.micro)

I ran stress-ng --vm 2 --vm-bytes 1G -t 60s while 5 people hammered Jot—zero crashes. The worst it did was delay comment polling by 1–2 seconds. Solid.

The Verdict: Is Jot Worth Deploying in 2024?

Yes—but with caveats.

I’ve run Jot for 19 days across 3 teams (12 people total) documenting infrastructure changes, RFCs, and incident post-mortems. It’s been shockingly stable. Zero downtime. Zero data loss. Our .jot files are in Git, and we’ve recovered comments twice after accidental rm -rf thanks to git checkout HEAD~3 -- *.jot.

Pros I didn’t expect:

• Team members actually use comments. Not just “+1”, but “This breaks on ARM64—see PR #42”. Because it’s low-friction and line-anchored, context stays sharp.
• The lack of features forces discipline. No “@mention” spam. No nested threads. Just: here’s the line, here’s the note.
• It’s fun to hack. I patched in a git commit button (30 lines of JS + a child_process.exec) that auto-commits .jot changes. Not in mainline—but trivial to add.

Rough edges that still sting:

• No comment author verification: The author field is set client-side. Anyone can claim to be “CTO” in a comment. Fine for trust-but-verify teams, dangerous for compliance.
• No markdown table editing: You have to write | col | col | manually. No WYSIWYG table builder.
• No dark mode toggle: It inherits system preference (works on Safari/Firefox, but Chrome ignores it). I patched index.html to force dark mode—your mileage may vary.
• File upload? Nope. You want images? Link to ImgBB or your own /static/ nginx alias.

Bottom line: Jot isn’t the future of collaborative editing. It’s a tool for a specific, underserved job: Git-native, line-anchored, zero-infrastructure markdown commentary. If that’s your pain point—and it was mine—then Jot is worth the 5 minutes it takes to docker compose up. It won’t replace your wiki. But it will kill the Slack thread titled “RFC-123 comments”.

The GitHub repo is small (83 stars, 41 forks), but the code is clean, the issues are responded to, and Mario merges PRs fast. It feels like a tool built by someone who uses it, not one designed to raise VC funding.

So go ahead—clone it. Tweak the CSS. Add that one feature you need. Then send a PR. That’s how minimal tools survive.