KumiDocs

A wiki and docs platform for small dev teams. No database: all content is stored in Git.

Try it now

cd /any/git/repo
bunx kumidocs

That's it. Open http://localhost:5864.

KumiDocs serves the current directory as its content store. Every save becomes a git commit. No setup, no config files required.

No Bun? Install it with curl -fsSL https://bun.sh/install | bash

Features

• Markdown editor: live split-pane, frontmatter, full history
• Slide decks: set slides: true in frontmatter; scroll, paginate, spotlight, fullscreen
• Code files: syntax highlighting via CodeMirror with language auto-detection
• Full-text search: fuzzy, Ctrl+K palette
• Real-time presence: edit lock, viewer avatars, live reload via WebSocket
• Image library: drag-and-drop upload, usage tracking, safe delete
• PDF export: pages (A4) and slide decks (landscape)
• SSO: any reverse proxy that forwards an email header (oauth2-proxy, Authelia, etc.)

Options

Point KumiDocs at a different repo or change the port:

bunx kumidocs --repo /path/to/repo --port 8080

All options are also available as environment variables:

| Flag | Env variable | Default | Description | | ------------------- | -------------------------- | --------------------- | ---------------------------------- | | --repo | KUMIDOCS_REPO_PATH | cwd | Path to the git repository | | --port | KUMIDOCS_PORT | 5864 | HTTP/WS listen port | | --auth-header | KUMIDOCS_AUTH_HEADER | X-Auth-Request-User | Header carrying the user identity | | --auto-save-delay | KUMIDOCS_AUTO_SAVE_DELAY | 5000 | Auto-save debounce in ms | | --pull-interval | KUMIDOCS_PULL_INTERVAL | 60000 | Background git pull interval in ms |

Production (Docker Compose)

Copy compose.yaml to your server and set your OAuth credentials:

SSO_PROXY_CLIENT_ID=your_client_id
SSO_PROXY_CLIENT_SECRET=your_client_secret
SSO_PROXY_PROVIDER=github            # github | google | oidc | ...
SSO_PROXY_REDIRECT_URL=https://docs.example.com/oauth2/callback
SSO_PROXY_COOKIE_DOMAIN=example.com
SSO_PROXY_COOKIE_SECURE=true

Mount your content repo at /repo:

volumes:
  - /path/to/your/content-repo:/repo

Then:

docker compose up -d

The stack runs KumiDocs on port 5864 (internal) behind oauth2-proxy on port 5865 (public).

Repository layout

KumiDocs reads and writes directly to the git repo it's pointed at:

README.md              # home page
.kumidocs.json         # instance config (optional)
images/                # uploaded images
**/*.md                # doc pages and slide decks
**/*.{ts,js,...}       # code files (read-only viewer)

.kumidocs.json (optional)

{
  "instanceName": "MyDocs",
  "editors": ["[email protected]", "[email protected]"],
  "slideThemes": {
    "my-corp": {
      "bg": "#1a2744",
      "fg": "#e8edf8"
    }
  }
}

If editors is set, only those users can write. Everyone else is read-only. Omit the field to let all authenticated users edit.

Page frontmatter

---
emoji: 📄
description: Shown in search results
slides: true # treat as slide deck
theme: corporate # built-in or custom theme name
paginate: true # show slide N/total badge
---

Building from source

bun install
bun run build   # outputs to dist/
bun start       # runs the production build