Inkstone
A self-hosted Markdown notebook for writing, organizing, syncing, and backing up personal knowledge.
中文 · Contributing · LGPL-3.0-only · Demo
About
Inkstone is a browser-based notebook that runs on Cloudflare Workers. Notes always remain plain Markdown text; on top of that foundation, the application provides focused writing, live preview, lexical and optional semantic search, bidirectional links, offline editing, multi-device synchronization, private AI access, public sharing, and off-site backups.
It is a complete self-hosted application. The deployer retains control of the database, attachments, and runtime environment.
Every new account automatically receives two standard starter notes, one in Chinese and one in English. The browser-only demo reuses the same note content; refreshing the page restores these two starter notes instead of loading a separate set of demo data.
Features
| Area | Included |
|---|---|
| Writing | CodeMirror 6 editor, independently editable note titles, two-note editor groups, per-group editor/split/preview layouts, synchronized scrolling, outline, focus mode, typewriter mode, autosave, and version history |
| Markdown | GFM tables and task lists, footnotes, Obsidian-style comments, WikiLinks, embeds, block IDs, callouts, details blocks, tabs, math, Mermaid diagrams, PrismJS syntax highlighting, and Front Matter |
| Organization | Nested folders with drag-and-drop ordering, inline tags, favorites, pinning, archive, trash, wiki links, backlinks, block references, note embeds, and a relationship graph |
| Search | D1 FTS5 full-text search with Chinese indexing, filters, recent notes, command-palette navigation, and optional private semantic/hybrid search powered by Workers AI |
| MCP | Private remote MCP, OAuth 2.1 with PKCE, revocable ink_... API keys, standard search/fetch, bounded reads, revision-safe writes, separate trash permission, and per-account grant management |
| Reliability | Installable PWA, offline app launch, browser-side cache, offline write queue and optimistic concurrency control, immediate local mutations with rollback, stale-sync protection, conflict copies, realtime notifications, and elected-tab polling fallback |
| Sharing | Public note links with optional access passwords and expiration dates |
| Portability | JSON and ZIP exports, directly readable Markdown, attachment export, and manual or scheduled WebDAV/S3 backups |
| Interface | Desktop and mobile layouts, dark/light themes, accent colors, Simplified Chinese, English, and owner-only update notifications |
Data storage
| Component | Purpose |
|---|---|
| Cloudflare D1 | Accounts, notes, folders, tags, settings, versions, shares, lexical indexes, per-account AI embeddings, and background indexing queues |
| Cloudflare R2 or Workers KV | Attachment and uploaded-avatar binaries through the FILES or FILES_KV binding |
Workers KV OAUTH_KV |
OAuth client registrations, authorization codes, access and refresh tokens, and grants; note bodies are not stored here |
Workers AI AI binding |
Optional embedding generation for semantic search; unavailable deployments continue to use lexical search |
| Browser IndexedDB | Local cache and pending offline writes |
SyncHub Durable Object |
Realtime change notifications between active clients |
CredentialVault Durable Object |
Isolated storage for the key used to encrypt backup credentials |
| WebDAV or S3 storage | User-configured off-site backups |
Deployment
- Fork the Inkstone repository to your GitHub account.
- Open Cloudflare Workers & Pages.
- Select Continue with GitHub, then choose your forked repository.
- For R2 mode, set the build command to
npm run buildand the deploy command tonpm run deploy.- To use KV mode, change the deploy command to
npm run deploy:kv.
- To use KV mode, change the deploy command to
- After deployment completes, open the generated Workers URL.
Existing databases are upgraded automatically through versioned, idempotent migrations. Keep a current backup before updating any self-hosted deployment. When a newer stable Inkstone release is available, the owner receives a focused reminder without interrupting regular members.
Exports and backups
- JSON export preserves legacy structured notebook data for re-import.
- ZIP export and remote backups use the same verified Markdown snapshot format, including readable notes, archived and trashed notes, attachments, and a completion marker.
- Remote backup targets support WebDAV and S3-compatible storage, with duplicate attachment content stored only once inside each snapshot.
- Large backups can be restored by selecting the backup folder, without loading one complete archive into memory.
- Multiple targets can be configured and run manually or on a schedule.
- Login passwords, active sessions, share passwords, and backup-service credentials are not included in exports.
Development and verification
| Command | Purpose |
|---|---|
npm run dev |
Start the local Worker and client |
npm run dev:kv |
Start locally with the KV attachment configuration |
npm run dev:demo |
Start the reset-on-refresh browser-only demo |
npm run typecheck |
Run TypeScript project checks |
npm run test:unit |
Run the Vitest unit test suite |
npm run i18n:check |
Verify parity between the English and Chinese locale resources |
npm run comments:check |
Enforce the source-comment policy |
npm run build |
Type-check and create a production build |
npm run deploy:kv |
Build and deploy with wrangler.kv.toml |
npm run deploy:demo |
Build and deploy the static browser-only demo |
npm run test:e2e |
Exercise the API against a running disposable local instance |
The end-to-end script creates, changes, and deletes data at http://localhost:7712. Run it only against a fresh local state dedicated to testing.
Repository layout
src/
├── client/ React interface, editor, preview, and local state
├── shared/ Shared types, limits, locale resources, and Markdown utilities
└── worker/ Hono API, authentication, D1 access, sync, sharing, and backups
public/ Static assets
scripts/ Repository checks and end-to-end verification scripts
tests/ Cross-module regression tests
Security and contributions
Read SECURITY.md before reporting a vulnerability. Development setup and contribution requirements are documented in CONTRIBUTING.md.
License
Inkstone is distributed under the GNU Lesser General Public License v3.0 only, using the SPDX identifier LGPL-3.0-only.