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 build and the deploy command to npm run deploy.
- To use KV mode, change the deploy command to npm run deploy:kv.
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.