Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/guanxiaol/obsidian-html

HTML-native note-taking. Your notes ARE the website. Obsidian alternative with WYSIWYG editor, AI gateway, E2E sync, sandboxed plugins, CLI. Tauri 2 + React.
https://github.com/guanxiaol/obsidian-html

ai-agent e2e-encryption html knowledge-graph local-first markdown note-taking notes notion-alternative obsidian obsidian-alternative pkm plugin-system react rust tauri web-clipper wysiwyg

Last synced: 6 days ago
JSON representation

HTML-native note-taking. Your notes ARE the website. Obsidian alternative with WYSIWYG editor, AI gateway, E2E sync, sandboxed plugins, CLI. Tauri 2 + React.

Awesome Lists containing this project

README 

          



Obsidian-HTML logo



Obsidian-HTML



Your notes are the website.





The first note-taking app where the file format is the rendering target.


No Markdown source/preview split. No syntax to learn. No exporters. No lock-in.


Edit a note in our app. Open the same .html in any browser. Embed it anywhere.






  GitHub stars

  latest release

  MIT

  CI

  Discussions






  Install

  ·

  Features

  ·

  Philosophy

  ·

  vs Obsidian

  ·

  Architecture

  ·

  中文








Obsidian-HTML editor screenshot — the same view as what the file looks like in a browser



The screenshot above is the editor. So is the file on disk. So is what you see when you open it in any browser. One file. Zero conversion.










---



## ✨ Highlights



- 🎨 **True WYSIWYG HTML editor** — TipTap + ProseMirror. No "source vs preview" mode. What you type is the file.

- 📂 **Local-first vault** — folder of `.html` files. Open them anywhere. Email them. Host them. Diff them in git.

- 🔗 **Wikilinks · backlinks · unlinked mentions · global graph (WebGL)** — full PKM toolkit, ~90 Obsidian-equivalent features mapped 1:1.

- 🎬 **Rich blocks Markdown can't reach** — video (YouTube/Vimeo/Bilibili/HLS), audio (8 codecs), PDF, charts, API-call widgets, web cards, inline SVG, MathML, KaTeX, Mermaid.

- 🧠 **AI gateway** — bring your own key for OpenAI, Anthropic, OpenRouter, Ollama, LM Studio, DeepSeek, or any OpenAI-compatible endpoint. Chat with your vault, rewrite selections, summarize.

- 🔒 **E2E encrypted sync** — point at iCloud / Dropbox / Google Drive / WebDAV / Nextcloud. AES-256-GCM + PBKDF2 200k rounds. Your provider sees ciphertext.

- 🔌 **Sandboxed plugins** — Web Worker isolation, typed RPC, install from any GitHub URL. Plugins **cannot** read your disk or steal your localStorage; they call into a controlled API surface only.

- ⌨️ **CLI for AI agents** — ships an `obh` binary so Claude Code, Codex, or any shell script can drive your vault programmatically (16 commands, `--json` output).

- 🌐 **Web Clipper** — Chrome MV3 extension powered by Defuddle (the same engine Obsidian's clipper uses).

- 📱 **One codebase, every platform** — Tauri 2 desktop (mac · win · linux) + iOS/Android (mobile builds).



---



## 🚀 Install



### macOS (Apple Silicon)



```bash

# Option 1: download the .dmg from GitHub Releases (recommended)

open https://github.com/guanxiaol/obsidian-html/releases/latest



# Option 2: build from source

git clone https://github.com/guanxiaol/obsidian-html.git

cd obsidian-html

bash scripts/setup.sh        # checks node/rust/xcode-clt, installs deps

pnpm tauri:dev               # launch desktop app

```



### Windows / Linux



```bash

git clone https://github.com/guanxiaol/obsidian-html.git

cd obsidian-html

bash scripts/setup.sh

pnpm tauri:build             # produces .msi / .deb / .AppImage

```



### Just the CLI (for AI agent integration)



```bash

cd obsidian-html

cargo build --release --bin obh --manifest-path src-tauri/Cargo.toml

./src-tauri/target/release/obh --help

```



Full prerequisites & troubleshooting: [QUICKSTART.md](QUICKSTART.md) · environment doctor: `pnpm doctor`.



---



## 🧠 Why HTML-first?



Every note app of the last fifteen years stores Markdown and renders it to HTML at display time. That transformation step is the **silent tax** on every PKM tool:



- It locks you into one renderer. Open your `.md` in any other tool and your callouts/wikilinks/embeds break.

- It forces a duality — "source" vs "preview". Live Preview is a clever bandage; the duality never fully heals.

- It caps your expressiveness at whatever the renderer supports. Want a chart? An API widget? Inline SVG? A real iframe? You need a plugin. The plugin emits HTML strings into the Markdown. The Markdown stops being portable.



We propose the inverse: **store the rendered form**.



HTML files _are_ documents. They open in browsers, render in emails, publish to the web, work in any embed context, and they support every visual primitive natively — video, interactive charts, inline SVG, custom elements, MathML — with zero conversion.



What you lose vs Markdown: nothing meaningful. We ship a WYSIWYG editor friendlier than Notion's. You never see angle brackets unless you want to.



What you gain: **every file ships as a real website**. Drag a note into a browser. Drop it into a Substack draft. Mail it. Host the folder on GitHub Pages — it _is_ the public site.



> "Markdown is a workaround for plain-text constraints that no longer exist. HTML doesn't have to be."



---



## 🎯 Features



### ✏️ Editor



- WYSIWYG HTML — no source mode

- Headings, lists, tables, task lists

- Code blocks with 200+ language highlights (lowlight)

- Tables with column resize

- Drag-and-drop attachments

- Multi-tab + split view

- Find & replace

- Command palette (`⌘P`)

- Quick switcher (`⌘O`)



### 🔗 Knowledge graph



- `[[wikilinks]]` with suggestions

- Backlinks + unlinked mentions panel

- Block refs `^id` & heading refs `#title`

- Embeds / transclusion `![[Note]]`

- Global WebGL graph (10k+ nodes)

- Local graph (N-hop neighborhood)

- Tag tree (nested `#a/b/c`)

- Properties (typed frontmatter)

- 6-operator search (`tag:` `path:` `-x` `OR` `"phrase"` `/regex/`)



### 🎬 Rich content



- 12 callout kinds (`note/tip/warning/...`)

- KaTeX math (inline + block)

- Mermaid diagrams

- Inline SVG + MathML

- 8 audio codecs + 7 video formats

- HLS / DASH streaming

- YouTube · Vimeo · Bilibili embeds

- PDF viewer (`.pdf` inline)

- iframes with host allowlist



### 🧠 AI



- BYO API key

- OpenAI / Anthropic native

- OpenRouter / Ollama / LM Studio / DeepSeek

- Streaming chat with vault context

- Selection → summarize / rewrite / translate

- Inline overlay (replace / insert / copy)

- Per-task model routing

- Token usage counter



### 🗄 Database (Bases)



- `.base` YAML files

- Table / cards (Kanban) / list views

- Filter expressions

- Sort + group by

- **Bidirectional**: edit cell → writes back to source note ``

- Drag cards between Kanban columns → rewrites property



### 🎨 Canvas



- JSON Canvas (Obsidian-compatible)

- Infinite pan + zoom

- Text / file / link / group nodes

- Drag, resize, connect

- Anchored edges

- Open `.canvas` from Obsidian → renders



### 🗓 Calendar (new in v1.0)



- `.calendar` file format (JSON, version 1)

- Month / Week / Day views

- Click empty slot → create event

- Drag to move events (15-min grid snap)

- Color categories (work / personal / health)

- Bilingual UI (`English / 中文`)

- Local wall-clock times (Apple Calendar style)



### 🔒 Sync & crypto



- WebDAV (Nextcloud, Synology, FastMail)

- iCloud / Dropbox / Drive / OneDrive auto-detect

- AES-256-GCM + PBKDF2 200k rounds

- Per-file `.obhx` blobs

- Conflict-free atomic writes (temp+rename)

- Auto-save with crash recovery

- IndexedDB drafts (lossless)



### 🔌 Plugins



- Web Worker sandbox

- 13-method typed RPC

- Install from GitHub URL (HTTPS-only, manifest verified)

- Per-plugin settings storage

- 3 sample plugins included

- No DOM / no localStorage / no native fetch — only API



### ⌨️ CLI & integrations



- `obh list / read / write / new / search / stats`

- `obh import-md / import-html / import-url`

- `obh sync push / pull` (WebDAV + folder)

- `obh encrypt / decrypt`

- `obh export-html` (static site)

- `--json` everywhere for piping

- Web Clipper (Chrome MV3)



### 🎨 3-mode editor (new in v1.0)



- **✎ Edit** — TipTap WYSIWYG (default for plain notes)

- **`>` Source** — raw HTML editor, no sanitize (AI's lane)

- **👁 Render** — sandboxed iframe, runs your CSS / JS

- Inline-edit on render (edits roundtrip to source)

- Auto-routing by content (rich notes → preview)



### 🤖 AI agent integration



- See [`AI 集成指南.html`](examples/vault-starter/AI%20%E9%9B%86%E6%88%90%E6%8C%87%E5%8D%97.html) in the starter vault

- Self-demonstrating rich HTML doc explaining the API

- Bilingual onboarding for Claude Code / Cursor / etc.

- "Notes are HTML" → AI writes any layout in one shot



---



## 🖼 What you can make



The starter vault (`examples/vault-starter/`) ships four polished case studies that exercise the full rendering pipeline — custom `` blocks, inline SVG charts, Google Fonts, drag-and-drop JS, all rendered identically in the app and in any browser.



<table>

<tr>

<td width="50%" valign="top">



<a href="examples/vault-starter/CEO%20%E5%AD%A3%E5%BA%A6%E5%9B%9E%E9%A1%BE%20Q2%202026.html"><img src="docs/screenshots/case-ceo.png" alt="CEO quarterly review case study"></a>



**📨 CEO Quarterly Letter** — A startup CEO's Q2 letter to the board: ARR numbers, 8-card KPI grid, hand-coded SVG charts (bar + donut + dual-line), OKR cards with progress bars, org chart, signed letter to "one year from now". Demonstrates production-grade business communication in a single `.html` file.



</td>

<td width="50%" valign="top">



<a href="examples/vault-starter/%E4%BA%BA%E7%94%9F%E8%A7%84%E5%88%92.html"><img src="docs/screenshots/case-life.png" alt="Life planning case study"></a>



**🎯 Life Plan v2026** — A 33-year-old's full life map: net worth tracker, FI progress, life-wheel SVG radar chart, habit tracker table with inline progress bars, relationship map, books and decisions log, letter to future self. Demonstrates personal planning at depth.



</td>

</tr>

<tr>

<td valign="top">



<a href="examples/vault-starter/%E6%89%8B%E8%B4%A6%E6%9D%BF%20%E2%80%94%20%E6%8B%96%E6%8B%BD%E6%BC%94%E7%A4%BA.html"><img src="docs/screenshots/case-board.png" alt="Drag-drop corkboard case study"></a>



**📌 Drag-Drop Corkboard** — Free-form sticky notes + polaroids + handwritten fonts. Drag anywhere; positions persist via `localStorage`. ⌘Z undo, ⌘⇧Z redo. **Real JavaScript runs inside the rendered note.** Demonstrates that "your note is the HTML" includes interactivity.



</td>

<td valign="top">



<a href="examples/vault-starter/AI%20%E9%9B%86%E6%88%90%E6%8C%87%E5%8D%97.html"><img src="docs/screenshots/case-ai.png" alt="AI integration guide"></a>



**🤖 AI Agent Guide** — A self-demonstrating bilingual onboarding doc for AI agents (Claude Code, Cursor, etc.) integrating with the vault. Explains the three view modes, working recipes, what AI can do via the source-mode + render workflow.



</td>

</tr>

</table>



### 🗓 Calendar (new in v1.0)



<img src="docs/screenshots/case-calendar.png" alt="Calendar view — Apple-style month / week / day">



Open the starter `Daily/我的日历.calendar` to see 8 example events spanning a month. Click empty slots to create events, drag to move them across days/times, switch between Month / Week / Day views, color-code by category.



---



## 🔬 vs The alternatives



|  | **Obsidian-HTML** | Obsidian | Notion | Logseq | Anytype |

|---|:---:|:---:|:---:|:---:|:---:|

| **File format** | `.html` (the rendering target) | `.md` (proprietary extensions) | proprietary DB | `.md` | proprietary DB |

| **Open in browser** | ✅ native | ❌ needs Publish | ❌ paid Publish | ❌ | ❌ |

| **WYSIWYG, no preview mode** | ✅ | ⚠️ Live Preview | ✅ | ❌ | ✅ |

| **Local-first** | ✅ | ✅ | ❌ cloud | ✅ | ✅ (sync via relay) |

| **Open source** | ✅ MIT | ❌ closed | ❌ closed | ✅ AGPL | ✅ AGPL |

| **E2E encrypted sync** | ✅ built-in | 💲 paid add-on | ❌ | ❌ | ✅ |

| **AI gateway (multi-provider)** | ✅ 6 backends | 💲 plugin | ✅ Notion AI | ❌ plugins | ❌ |

| **CLI for AI agents** | ✅ `obh` | ❌ | ❌ API | ❌ | ❌ |

| **Embeds (video/PDF/API/charts)** | ✅ native HTML | ⚠️ plugins | ✅ | ⚠️ | ⚠️ |

| **Plugin sandbox** | ✅ Web Worker | ⚠️ in-realm JS | ✅ | ⚠️ in-realm JS | ✅ |

| **Bundle size** | 6.5 MB (.dmg) | ~100 MB | n/a (web) | ~150 MB | ~200 MB |

| **Mobile** | 🟡 Tauri 2 mobile | ✅ | ✅ | ✅ | ✅ |

| **Founder lock-in risk** | none (your files are HTML) | high (Markdown dialect) | very high | low | medium |



---



## 🏗 Architecture



```

┌──────────────────────────────────────────────────────────────┐

│                     Tauri 2 Desktop Shell                    │

│                   (mac · win · linux · iOS · Android)        │

├──────────────────────────────────────────────────────────────┤

│  Frontend: React 18 + TipTap 2 (ProseMirror) + Zustand       │

│  ├─ 11 TipTap extensions (wikilink, callout, math, mermaid…) │

│  ├─ 8 interactive block types (video, API, chart, PDF, …)    │

│  ├─ 13 panel components (file tree, graph, properties, AI…)  │

│  ├─ AI gateway (Vercel AI SDK wrap, 6 providers)             │

│  └─ Plugin host (Web Worker + typed RPC, 13 methods)         │

├──────────────────────────────────────────────────────────────┤

│  Backend: Rust (Tokio + reqwest + aes-gcm + pbkdf2)          │

│  ├─ vault_ops: atomic file r/w with traversal guards         │

│  ├─ crypto: AES-256-GCM E2E layer                            │

│  ├─ sync: WebDAV PROPFIND/PUT + folder sync                  │

│  ├─ fetcher: HTTP proxy w/ SSRF + private-net blocking       │

│  └─ obh CLI: 16 subcommands, --json output                   │

├──────────────────────────────────────────────────────────────┤

│  Storage: .html files + .obsidian-html/ config dir           │

│            + IndexedDB drafts (crash recovery)               │

│            + localStorage (settings, no secrets in v0.1)     │

└──────────────────────────────────────────────────────────────┘

```



### Design decisions, briefly defended



| | Choice | Why not the alternative |

|---|---|---|

| Desktop | **Tauri 2** | Electron = 100MB and 500MB RAM. Tauri = 6.5MB DMG. |

| Editor | **TipTap / ProseMirror** | Lexical = worse table support. Slate = stability issues. `contenteditable` = no thanks. |

| State | **Zustand** | Redux = ceremony. Context = re-render hell on edit-heavy apps. |

| Crypto | **AES-256-GCM + PBKDF2 200k** | Argon2id better but `aes-gcm` crate is unimpeachable. Path is open for v2. |

| Plugin sandbox | **Web Worker** | iframe = leakier. WASM-only = limits API. Worker hits the sweet spot. |

| AI | **Vercel AI SDK + `openai-compatible`** | Reinventing the wheel for 6 providers is silly when LangChain-equivalents exist. |

| Sync | **WebDAV first, vendor protocols later** | WebDAV is universally available; iCloud-direct requires platform crypto. |



---



## 📊 By the numbers



| | |

|---|---|

| Source files | **138** |

| TypeScript LOC | **12,500** |

| Rust LOC | **2,800** |

| Frontend tests | **85** (Vitest) |

| Backend tests | **11** (Cargo, includes 8 security tests) |

| Bundle | **6.5 MB** (.dmg) · **21 MB** CLI |

| Features mapped from Obsidian | **90+** (~95% coverage) |

| AI providers supported out of the box | **6** (extensible) |

| Phases delivered | **5/5** (MVP → ecosystem) |



---



## 📜 The OBH Spec — a format, not just an app



This project ships two foundational documents intended for **adoption by other tools**:



- **[`docs/SPEC.md`](docs/SPEC.md)** — vendor-neutral spec for HTML-as-storage notes (semver, 14 sections, 5 conformance levels). Anyone can implement it; vaults stay portable across tools.

- **[`docs/AGENT_API.md`](docs/AGENT_API.md)** — the stable surface for AI agents (Claude Code, Codex, shell scripts) to read and write vaults: the `obh` CLI, an experimental JSON-RPC server, and reference snippets for Python / Node / Rust / shell to talk to files directly.



The bet: the format is the moat. If another note-app implements OBH, users can move between us without conversion. We'd see that as a win.



---



## 🌐 Self-host & publish



Your notes ARE the website — there's no separate "publish" target. A vault folder of `.html` files is already a working static site.



```bash

obh export-html ~/MyVault ./dist

# Now upload ./dist anywhere:

wrangler pages deploy ./dist            # Cloudflare Pages

rsync -avz ./dist/ srv:/var/www/notes/  # Personal nginx / Caddy

netlify deploy --prod --dir=./dist      # Netlify

```



The full playbook — **personal server (nginx + Caddy configs), Cloudflare Pages, Cloudflare Workers + R2, GitHub Pages, Vercel/Netlify, GitHub Actions auto-publish, custom domain + HTTPS, private notes, secondary development (forking, plugins, CLI scripting)** — lives in [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md).



---



## 🛣 Roadmap



- [x] **Phase 1** — MVP: vault, tabs, WYSIWYG editor, file tree, drag-drop attachments

- [x] **Phase 2** — Knowledge graph: wikilinks, backlinks, properties, search, command palette, Obsidian import

- [x] **Phase 3** — Rich content: WebGL graph, transclusion, math, mermaid, themes

- [x] **Phase 4** — Power features: Canvas (JSON Canvas), Bases (bidirectional), interactive blocks

- [x] **Phase 5** — Ecosystem: AI gateway, WebDAV/iCloud/E2E sync, sandboxed plugins, CLI, Web Clipper, mobile build config

- [ ] **Phase 6** — Mobile builds shipped to App Store / Play Store

- [ ] **Phase 7** — Real-time collaboration (Y.js / CRDT)

- [ ] **Phase 8** — Plugin marketplace (curated GitHub registry)

- [ ] **Phase 9** — Argon2id migration + OS-keychain credential storage



[Open an issue](https://github.com/guanxiaol/obsidian-html/issues/new/choose) if you'd like to push a future phase forward.



---



## 🤝 Contributing



Yes, please! Read [CONTRIBUTING.md](CONTRIBUTING.md) — it covers:



- Dev setup in 60 seconds (`bash scripts/setup.sh`)

- How the codebase is organized

- Coding conventions

- PR checklist (tests must stay green, TS must compile, Cargo must check)

- Security disclosure policy ([SECURITY.md](SECURITY.md))



First time? Look for issues labeled [`good-first-issue`](https://github.com/guanxiaol/obsidian-html/labels/good-first-issue).



---



## 💬 Community



- 💡 [Discussions](https://github.com/guanxiaol/obsidian-html/discussions) — feature requests, Q&A, show & tell

- 🐛 [Issues](https://github.com/guanxiaol/obsidian-html/issues) — bug reports

- 🔒 [Security advisories](https://github.com/guanxiaol/obsidian-html/security) — private vulnerability disclosure

- 📖 [中文 README](README.zh-CN.md) · [Quickstart](QUICKSTART.md) · [Mobile guide](MOBILE.md) · [Project plan](PLAN.md)



---



## 📜 License



[MIT](LICENSE) © 2026 [guanxiaol](https://github.com/guanxiaol)



The project gratefully builds on: [Tauri](https://tauri.app), [TipTap](https://tiptap.dev), [ProseMirror](https://prosemirror.net), [React](https://react.dev), [Defuddle](https://github.com/kepano/defuddle), [Vercel AI SDK](https://sdk.vercel.ai/), [DOMPurify](https://github.com/cure53/DOMPurify), [KaTeX](https://katex.org), [Mermaid](https://mermaid.js.org), [Sigma.js](https://sigmajs.org).



<br>



<div align="center">

<sub>If this project pushes the note-app conversation forward, a ⭐ helps it reach more people. Thanks for reading.</sub>

</div>