Website · Download · Contributing
A lightweight, local-first notes app. Your notes are plain Markdown files in a folder you choose. No dependencies, no build step, no accounts, no telemetry: just Node.js.
node server.js [notesDir] [port]
# e.g.
node server.js ~/Notes # http://localhost:4777notesDir defaults to ./notes and port to 4777 (or $PORT). Requires Node.js 20+. You can point it at an existing Obsidian vault or any folder of .md files.
First run: open Plainnote on an empty notes folder and a 60-second tour starts by itself, offering to add a small set of sample notes (a welcome page, Markdown basics, links and the graph, diagrams, your files). Existing notes are never touched and never overwritten, and the tour never starts for a folder that already has notes. Retake it any time from the command palette (Take the Plainnote tour, Add the sample notes).
-
Images and PDFs: paste or drop a
.png,.jpg,.gif,.webp,.svgor.pdfinto the editor. It is saved underattachments/and linked as. In the reading view, PDFs show in an inline viewer and images open full size when clicked (Esc closes). -
Diagrams: a fenced block named
diagramdraws a flow or sequence diagram as SVG (follows light/dark, prints cleanly). Hover one in the reading view to copy it as SVG, copy it as an image, or save a PNG.```diagram title: Signup (Start) -> Enter email #blue -> {Valid?}: yes {Valid?} --> Show error #red: no Enter email -> [(Users DB)] #green ```One chain per line, with
: labelon the last arrow.->is an arrow,-->a dashed arrow,---a plain line. Shapes:Namerounded box,(Name)pill,{Name}diamond,[(Name)]database,((Name))circle. Add a colour with#blue #green #orange #pink #teal #gold #red #grayor#rrggbb. Header lines:downfor top-to-bottom,title: …. For a sequence diagram start withsequence, thenBrowser -> Server: POST /loginandServer --> Browser: 200(dashed is a reply). -
Math:
$e^{i\pi}+1=0$inline and$$ … $$blocks (one line or several). A LaTeX subset (fractions, roots, sub/superscripts, sums and integrals with limits, Greek letters, common symbols, matrices andcases) is drawn as MathML, which browsers render natively, so there is nothing to download. Prices like "$5 and $10" and anything inside code are left alone; an unknown command shows in red instead of breaking the note. -
Charts: a
chartfence draws a bar, line or pie chart as SVG:```chart bar title: Sales series: 2025, 2026 Jan: 12, 15 Feb: 18, 21 ```The first line is
bar,lineorpie(defaultbar);title:andseries:are optional, and each row islabel: value(or several values for several series). -
Web clipper: run Web clipper: get the Clip bookmark… from the command palette and drag the link to your bookmarks bar. On any page, select some text (or nothing, to take the main article) and click it: a small window opens on your own server showing the page as Markdown (headings, links, lists, tables, code and images kept; menus, ads and scripts dropped) to edit and save into
Clippings/, with the source link and a#clippingtag. Nothing is sent anywhere else, and it never overwrites an existing note. The bookmark points at the address Plainnote is running on, so use a fixed port (node server.js ~/Notes 4777); the Mac app picks a new port each launch. -
Markdown to PDF from the terminal:
node server.js export note.md [out.pdf]uses the app's own renderer and an installed Chrome, Edge or Chromium (setCHROME=/pathto choose). In the app, use Export this note as PDF. -
Edit PDFs (optional add-on; run
npm install pdf-lib --no-saveonce, the app itself stays dependency-free):node server.js pdf info a.pdf node server.js pdf merge out.pdf a.pdf b.pdf node server.js pdf extract in.pdf 1,3-5 out.pdf # keep these pages node server.js pdf delete in.pdf 2 out.pdf node server.js pdf rotate in.pdf 90 out.pdf [pages] node server.js pdf stamp in.pdf "DRAFT" out.pdf [pages]
- Version history: Plainnote keeps earlier versions of each note in
.plainnote/history/(at most one every 2 minutes, newest 60 kept; plain files, no git needed). Run Version history of this note… from the command palette to preview a version and restore it. Restoring is an ordinary edit, so you can undo it from history too. Not in the iPhone app yet. - Publish a website:
node server.js publish ~/Notes ./site --title "My notes"writes one HTML page per note plus an index and the attachments you used.[[links]]become real links, light/dark follow the visitor's system, anddiagramblocks and PDFs come along. Putpublish: falsein a note's frontmatter to keep it out (links to it become plain text). The output folder must be empty or a previous publish, and inside your notes it must be a dot-folder, so nothing of yours is overwritten. Push the folder to GitHub Pages or any static host.
Run Import notes from another app… from the command palette (or node server.js import <folder-or-zip> [notesDir] for Markdown, from the terminal). Pick what you exported and Plainnote turns it into plain Markdown files, keeping folders, links, images, tags and dates:
| From | Export | Choose |
|---|---|---|
| Obsidian | nothing to export | the vault folder (or a .zip of it) |
| Notion | Settings → Export → Markdown & CSV (or HTML) | the .zip |
| Evernote | File → Export Notes… → .enex |
the file (images and attachments come along; checklists become tasks) |
| Bear and others | Export as Markdown or TextBundle | the folder or .zip |
Notion's long id suffixes are removed from names, links between pages become [[wikilinks]], database CSVs become tables, and images are saved into attachments/. Imported notes go into an Imported folder by default (leave the name empty to merge into your notes). Nothing is ever overwritten: a name that is taken gets a number, and the preview tells you what was found and what was skipped (for example .docx or audio files, which Plainnote does not keep). Zips are checked before they are read: unsafe paths, hidden files, password-protected and oversized archives are refused or skipped. Evernote and HTML need the in-app importer; the terminal command handles Markdown, CSV and images.
Run Encrypt this note… from the command palette and choose a passphrase. The note is then stored as encrypted text (AES-256-GCM, key from your passphrase with PBKDF2-SHA256, 600,000 rounds, done by the browser's own crypto, nothing to install). It is still an ordinary file in your folder, so git sync and backups keep working. Opening it asks for the passphrase; it stays unlocked in memory only, and locks again after 10 minutes of inactivity or with Lock this note now / Lock all encrypted notes. Change this note's passphrase… and Remove encryption from this note… are in the palette too.
While a note is locked, Plainnote sees none of its text: search, the graph, backlinks, find-and-replace and embeds in other notes skip it, and nothing can save over it. There is no recovery: forget the passphrase and the note is gone. What is not protected: the note's name, size and dates; earlier plain-text copies that already exist (version history, git history, backups, the trash, Spotlight); and anything on a machine that has malware or a keylogger. Quick capture and the URL scheme refuse to append to an encrypted note, node server.js publish skips encrypted notes (they are never put on a website), and node server.js export refuses them. Version history shows and restores the plain text of an encrypted note's older versions while it is unlocked. Encryption needs a secure connection (localhost or https), so over plain http on a LAN it is unavailable. The iPhone app shows the same lock screen but its quick-capture route does not yet refuse to append.
You never depend on Plainnote to read your notes. The file is:
-----BEGIN PLAINNOTE ENCRYPTED NOTE-----
Version: 1
KDF: PBKDF2-SHA256
Iterations: 600000
Cipher: AES-256-GCM
Salt: <base64, 16 bytes>
IV: <base64, 12 bytes>
<base64 of ciphertext followed by the 16-byte GCM tag>
-----END PLAINNOTE ENCRYPTED NOTE-----
key = PBKDF2-HMAC-SHA256(NFKC(passphrase) as UTF-8, Salt, Iterations, 32 bytes), decrypt with AES-256-GCM using IV, with the additional authenticated data plainnote-enc-v1; the plaintext is the note's UTF-8 text. (tests/crypto.test.js opens a note with Node's crypto module alone, and the reverse.)
Run Back up all notes (.zip)… from the command palette to download one .zip of everything Plainnote stores: your notes, attachments (images and PDFs), custom CSS snippets and version history. It leaves out the trash, git data, the remote-access token and any other files. It streams, so a very large folder does not use much memory (a 600 MB folder took about 90 MB). In the Mac app, where a window cannot download files, the backup is written to your Downloads folder instead. The iPhone app has no server; its notes are plain files in Files / iCloud Drive and back up with your phone.
Restore notes from a backup… shows what a restore would do before it does anything, then only adds: a file you already have is never overwritten. A note that differs from the backup's version is kept as a separate Note (restored 2026-11-22).md next to it, and restoring again does not pile up copies. Files in a backup are checked (paths, types, sizes and checksums), so a damaged or hostile zip cannot write outside your folder, and a damaged file is skipped without stopping the rest. Encrypted notes are backed up as the encrypted text they already are.
From the terminal (a good fit for cron or a scheduled task):
node server.js backup ~/Notes ~/Backups/ --keep 14 # a dated .zip in that folder, keeping the newest 14
node server.js backup ~/Notes ~/Backups/notes.zip # or one named file
node server.js restore ~/Backups/notes.zip ~/Notes --dry-run
node server.js restore ~/Backups/notes.zip ~/NotesBackups are plain zip files that any unzip tool opens. One zip holds up to 4 GB and 65,535 files; beyond that, use git sync.
- Find anything: ⌘/Ctrl+K jumps to (or creates) a note and matches by initials (
mnfinds Meeting Notes), folder and alias; ⌘/Ctrl+Enter opens it in a new tab. ⌘/Ctrl+Shift+P is the command palette, grouped, with your recent commands first. ⌘/Ctrl+/ shows every shortcut, including your own and the editor's (bold ⌘B, italic ⌘I,strike⌘⇧X, ==highlight== ⌘⌥M,code⌘⌥C, heading level ⌘⌥H, tick a task ⌘Enter). - Nothing is lost, and mistakes are undoable: deleting a note, a replace across all notes and a history restore each offer Undo instead of asking first. If a save fails, the status reads Not saved with a Retry button, the text stays in the window, other notes' edits are not forgotten when you switch, and Plainnote retries by itself. Closing the page makes a last-chance save.
- Reading view: nested lists, tasks you can tick in place (they rewrite the line in the note), a hover button on each heading that copies a
[[Note#Heading]]link, and a Copy button on code blocks. - Settings: list order and a text preview line, editor line spacing, and how long to wait before saving.
- Large vaults: reloads fetch only the notes that changed, and the app files are compressed and revalidated.
node scripts/bench-ux.js --notes 10000measures it on a generated vault (opening a note went from 17 s to 24 ms on 10,000 notes, and a tag filter from 41 ms to 1 ms). - Accessibility and touch: the note list, tags, tabs, palette and dialogs work from the keyboard and with a screen reader (arrow keys, Enter, Shift+F10 for the context menu); focus is trapped in dialogs and returned; colours meet WCAG AA in both themes; every touch target is at least 44 × 44, and the on-screen keyboard no longer covers the caret on an iPad.
./desktop/build.sh # builds dist/Plainnote.app (needs Xcode command line tools)
open dist/Plainnote.appA native wrapper (Swift + WKWebView, no Electron), universal for Apple Silicon and Intel. It has a translucent sidebar and full-size window, a real menu bar, a Dock menu and a menu-bar icon, and integrates with macOS:
- Quick capture: press Ctrl+Option+N anywhere to jot a line into today's daily note without leaving what you're doing (⌘↩ saves, esc cancels).
plainnote://links:plainnote://open/<note>,plainnote://today,plainnote://new?title=…&text=….- Open files and folders: open a
.mdfile from Finder, or drop a folder on the Dock icon to use it as your notes folder. - Services: select text in any app, then Services ▸ New Plainnote from Selection.
- Share the open note from the File menu, and sync notifications when the app is in the background.
A tiny native wrapper (Swift + WKWebView, no Electron). It starts the bundled server on a free local port, shows it in a window, and stops it on quit. Node.js must be installed. File → Choose Notes Folder… switches folders (default ~/Notes). Local builds are ad-hoc signed. For distribution, build with SIGN_ID="Developer ID Application: …" ./desktop/build.sh (hardened runtime), then sign the DMG and run xcrun notarytool submit <dmg> --key AuthKey.p8 --key-id … --issuer … --wait and xcrun stapler staple <dmg>. CI does all of this on tagged releases when these repository secrets are set: MACOS_CERT_P12 (base64 .p12), MACOS_CERT_PASSWORD, MACOS_SIGN_ID, NOTARY_KEY_P8 (base64 App Store Connect API key), NOTARY_KEY_ID, NOTARY_ISSUER_ID. Without them it produces an unsigned-for-distribution DMG. To release without storing the certificate in GitHub, run ./scripts/release.sh <version> on a Mac that has the Developer ID identity and a notary notarytool profile: it tags, builds, signs, notarizes, staples and publishes the release (CI supplies the Linux and Windows binaries).
A native app (SwiftUI + WKWebView) that bundles the same interface and needs no server and no network: the file operations are done in Swift (ios/Sources/NotesStore.swift, Router.swift), against a folder of .md files. It opens notes in a reading view (tap the text to edit), has a tab bar, bottom-sheet panels, note previews, haptics and a formatting bar above the keyboard, and follows light/dark mode. Notes live in the app's own Files → On My iPhone → Plainnote folder, or any folder you pick in Settings → Notes folder (iCloud Drive keeps it in sync with your Mac). Git sync is a desktop feature; on iOS use iCloud Drive or another Files provider.
./ios/build.sh test # XCTests: the Swift routes against the same rules as tests/server.test.js
./ios/build.sh selftest # build, launch twice in the simulator, drive the real UI through the native bridge
./ios/build.sh build # simulator build (open ios/Plainnote.xcodeproj in Xcode to run it)
DEVELOPMENT_TEAM=<team id> ./ios/build.sh archive # signed device archive (needs your Apple developer account)
./ios/build.sh icon # regenerate the app and web-app icons from desktop/icon.swiftNeeds Xcode 15+ and xcodegen (brew install xcodegen). Not included: App Store submission, widgets, a share extension.
Plainnote is also an installable web app (PWA) for Android and any phone browser. The notes stay on your computer: start the server in remote mode and open it from the phone.
node server.js ~/Notes 4777 --remote # still bound to 127.0.0.1; prints a link ending in ?token=…
tailscale serve --bg 4777 # then open https://<your-mac>.<tailnet>.ts.net/?token=… on the phone
node server.js ~/Notes 4777 --remote --host 0.0.0.0 # or listen on your LAN (plain http, so no install prompt)Remote mode needs the secret token on every request (a cookie set by the link, or an Authorization: Bearer header). The token is generated once and kept in <notes>/.plainnote/token (owner-readable only; delete the file to rotate it), compared in constant time, and repeated wrong guesses are throttled. Without --remote nothing changes: localhost only, no login. Because the token is the only gate, serve it over HTTPS (Tailscale Serve, a reverse proxy) whenever it leaves your machine, and don't share the link. Then use Add to Home screen (Android Chrome: Install app; iPhone Safari: Share → Add to Home Screen). The app shell works offline; notes always come from the server.
A single downloadable executable, no Node install needed. Build it on the target OS:
node scripts/build-sea.js # -> dist/plainnote-<platform>-<arch>[.exe]CI builds all three platforms: run the build-desktop workflow, or push a v* tag to attach the executables to a GitHub release (the macOS build also attaches a universal Plainnote-<version>-universal.dmg).
It starts the notes server on 127.0.0.1 and opens it in a standalone app window using an installed Chrome, Edge, Chromium or Brave (Edge ships with Windows), falling back to your default browser. Closing the window quits the app. Launching it again opens another window on the running instance.
plainnote # notes in ~/Notes
plainnote --notes D:\Notes # or set PLAINNOTE_DIR
plainnote --no-window # server only, open the printed URL yourselfPLAINNOTE_BROWSER points at a specific browser. On Linux, desktop/linux/plainnote.desktop is a starter launcher entry. Without Node installed you can also run the launcher directly with node desktop/launcher.js. On Windows a console window stays open while the app runs; the executable is unsigned, so SmartScreen may warn on first run.
- Markdown files on disk: subfolders work (
folder/name); anything that reads Markdown can open them. - Wikilinks
[[Note]]/[[Note|alias]]with autocomplete as you type[[. Links to missing notes are created on click. Renaming a note updates links to it. - File tree: switch the sidebar between List and Files. Drag a note onto a folder to move it (links to it are rewritten, including
[[Note#Heading]]), right-click for Rename, Duplicate, Move to folder, Pin, Copy link, new folder and more. Empty folders are kept. - Tabs and a split pane: Cmd/Ctrl-click a note or link (or right-click → Open in new tab) to open it in a new tab; tabs are restored when you relaunch. Option/Alt-click a link, or use Open to the right, to keep a second note beside the one you're editing as a live read-only preview.
- Settings (Cmd/Ctrl+, or the command palette): theme, reading font and width, text size, an accent colour that overrides the system one, the daily-notes folder and template, and a default folder for new notes. Add custom shortcuts for any command (on top of the built-in ones), and drop CSS files into
.plainnote/snippets/in your notes folder to restyle the app: enable them in Settings (snippets are trusted code, so only use ones you've read). - Live Preview (beta): turn it on in Settings or with the Toggle Live Preview editor command. The line with the caret shows raw Markdown; every other line renders in place (headings, bold/italic/code/highlights, links, lists, quotes, checkboxes you can tick). Not there yet: find in note,
[[completion, the slash menu, image paste, and selections that cross rendered lines can land a few characters off. - Properties: a panel above each note edits its frontmatter (text, number, date, checkbox, lists) without touching the rest of the file; notes without properties just offer + Add property.
- Backlinks for every note, and a graph view (drag, pan, zoom, click to open).
- Tags:
#tagor#parent/child, filter from the sidebar. - Full-text search with snippets, and a quick switcher. The sidebar search understands
"exact phrase",tag:idea,path:work/,file:plan,-excluded, and/regex/; save a search as a chip. - Smarter links:
[[Note#Heading]]and[[Note^block]](end a line with^id) jump to the spot, frontmatteraliases:resolve to the note,[[Note#autocompletes headings, hovering a link previews the note, and each note lists the notes it links to as well as its backlinks. - Preview with tables, images (remote or from your folder), task lists and syntax-highlighted code blocks.
- Live syntax highlighting while you edit (headings, bold, links, wikilinks, tags, code blocks with per-language colours).
- Slash menu: type
/at the start of a line for headings, tasks, tables, code blocks, dividers, links and today's date. - Writing tools: note templates (
templates/folder,{{date}}{{title}}), find and replace (Ctrl/Cmd+F), focus mode (Ctrl/Cmd+Shift+F). - Knowledge tools:
> [!tip]callouts,==highlights==, footnotes,![[Note]]/![[Note#Heading]]embeds, YAML frontmatter (tags:count as tags), unlinked mentions with one-click linking, and an all-notes open-tasks view (command palette). - Editor niceties: list continuation, Tab/Shift+Tab indent, Cmd/Ctrl+B and +I, paste or drop images (saved to
attachments/). - Safe by default: autosave, deletes go to
.trash/(restore from the Trash button), and if a note changes on disk underneath you (sync, another window) your version is saved as a "conflict" copy instead of overwriting. - Git sync, manual or every 2 minutes.
- Light, dark or follow-the-system theme (toggle at the top of the sidebar, remembered), and a narrow-screen layout.
| Key | Action |
|---|---|
| Ctrl/Cmd+K | Quick switcher (jump or create) |
| Ctrl/Cmd+Shift+P | Command palette (every action, searchable) |
| Ctrl/Cmd+N | New note |
| Ctrl/Cmd+, | Settings |
| Ctrl/Cmd+T / W | New tab / close tab |
| Ctrl/Cmd+Shift+[ / ] | Previous / next tab |
| Ctrl/Cmd+Alt+\ | Open this note in a split pane to the right |
| Ctrl/Cmd+E | Toggle edit / preview |
| Ctrl/Cmd+G | Toggle graph view |
| Ctrl/Cmd+S | Save now |
| Ctrl/Cmd + / - / 0 | Larger / smaller / reset text size |
| Ctrl/Cmd+[ / ] | Back / forward through opened notes |
| Ctrl/Cmd+Shift+T | Open today's daily note (daily/YYYY-MM-DD) |
| Ctrl/Cmd+Shift+L | Cycle theme (auto / light / dark) |
| Ctrl/Cmd+F | Find and replace in the note |
| Ctrl/Cmd+Shift+F | Focus mode |
| Ctrl/Cmd+B / I | Bold / italic |
| Tab / Shift+Tab | Indent / outdent |
The notes folder is just files, so sync uses git:
- Create an empty private repo on your git host.
- Click Sync (bottom of the sidebar) and enter the remote URL (
https://…,ssh://…orgit@host:user/repo.git). - Each sync commits changes, pulls with rebase, and pushes. On a conflict the rebase is aborted and an error is shown; nothing is lost locally.
- Tick Auto to sync every 2 minutes while the tab is visible.
Authentication is whatever git already uses on your machine (SSH keys, credential helper). Prefer iCloud, Dropbox or Syncthing? Point the app at a folder inside one and ignore the Sync button.
- Listens on
127.0.0.1only and rejects requests whoseHostisn't localhost (DNS-rebinding) or whoseOriginis another site. - Note paths are confined to the notes folder; only image files are served from it, SVGs sandboxed.
- Sync remotes are limited to
https://,ssh://andgit@host:pathURLs. - There is no authentication: anyone with access to your local machine's port can read your notes. Don't expose the port.
npm test # node --test: markdown/editor unit tests, server API tests, and a headless-Chrome UI testThe UI test drives the real app through the Chrome DevTools protocol (no dependencies) and is skipped if Chrome isn't installed. UI_SHOTS=dir npm test saves screenshots.
Tests run on your own machine rather than on GitHub: npm run setup-hooks (once per clone) installs a pre-push hook that runs npm test before every push and stops the push if it fails. Skip it for one push with SKIP_TESTS=1 git push. The website and release workflows still run on GitHub; the test workflow is switched off.
server.js zero-dependency HTTP server + file/git API
public/index.html the page shell; public/app.css and public/app.js hold the UI (plus manifest.webmanifest, sw.js and icons for the web app)
ios/ the iPhone/iPad app (Swift sources, XCTests, build.sh)
public/md.js Markdown renderer and editor helpers (shared with the tests)
desktop/ macOS wrapper (Plainnote.swift, build.sh), cross-platform launcher.js, Linux .desktop
scripts/build-sea.js builds the single-file executable
tests/ unit, API and browser tests
docs/ the website (GitHub Pages) and its screenshots
The editor is a plain textarea, not a full code editor. The graph layout is O(n²): fine for a few hundred notes. The Windows/Linux builds are produced by CI and haven't been tested by hand on those systems; the macOS wrapper needs Node installed. No encryption at rest and no built-in auth (it relies on being local-only).
Please contact sales@zyvor.dev before sending a contribution; contributions are accepted only under the terms of the Zyvor Production Licence v2.0. See CONTRIBUTING.md and the Code of Conduct. Report security problems privately (SECURITY.md).
Plainnote: A 30-day trial is available on request from sales@zyvor.dev (a paid evaluation Order at no charge); production and any other use needs a paid Order under the Zyvor Production Licence v2.0. If it helps you, you can give any amount you like, from INR 1 up: by UPI, card or netbanking at https://rzp.io/rzp/utwdYh3 (Razorpay; international cards work too). Suggested: INR 999 (about US$10), INR 2,999 (about US$30) or INR 9,999 (about US$100). A donation is voluntary and supports development and maintenance. It is not a purchase: it buys no support, SLA, features, priority or licence, and it is not tax-deductible (Zyvor AI Labs Private Limited is a company, not a charity).
Plainnote is source-available under the Zyvor Production Licence v2.0 (SPDX LicenseRef-Zyvor-Production-2.0, also in LICENSES/; see NOTICE, which also records the earlier MIT-licensed history).
- A 30-day trial is available on request from sales@zyvor.dev (a paid evaluation Order at no charge); production and any other use needs a paid Order under the Zyvor Production Licence v2.0.
- Production use needs a paid Order from Zyvor AI Labs. Buy / get a quote: zyvor.dev/buy · sales@zyvor.dev.

