Contributing

n0te is MIT-licensed. Its repository isn’t public yet; this page is for working on n0te once it is, and for whoever is working on it already. Bug reports, fixes and docs improvements will be welcome. For a bigger change, open an issue first, so we can talk about whether it fits: n0te stays small on purpose.

Build and test

cargo build --release      # 0 warnings
cargo clippy --release     # 0 warnings too
cargo test --release       # unit tests

The unit tests cover splicing, merging, undo, tasks, lists and the updated: date in the app, and config, vault detection, the runtime folder and setup in the library. GTK tests run when there’s a display and are skipped otherwise.

N0TE_APP_ID=dev.n0te.Check target/release/n0te-app --check

--check renders every note in your vault and must report 0 with leftover syntax and 0 that don't round-trip. Run it after any change to the renderer. tests/fixtures/kitchen-sink.md has every construct the renderer handles.

Run a test instance next to your own

Your own n0te service keeps running while you work. To try a build without touching it:

N0TE_APP_ID=dev.n0te.Something runs a separate instance under its own app id.
N0TE_VAULT=target/test-vault, pointing at a copy of a vault, keeps tests from writing to your real notes.
To try setup or the settings page, point HOME and XDG_CONFIG_HOME, XDG_DATA_HOME and XDG_STATE_HOME at a sandbox (your shell may set the XDG ones explicitly), and unset HYPRLAND_INSTANCE_SIGNATURE so n0te doesn’t reload your Hyprland.

Driving a window from a script

N0TE_VAULT=<copy> bench/script.sh OUT FILE STEPS

bench/script.sh runs n0te on GTK’s Broadway backend with a headless Chromium as its viewer, so nothing appears on your screen and nothing takes focus. A steps file (keys, typing, clicks on text, scrolls, waits, screenshots) runs against a copy of FILE, and the log shows every scroll change with the step that caused it, plus where blocks and the caret are. The steps are documented at the top of src/bin/n0te-app/script.rs.

bench/drive.sh does the same with a real, floating window, wtype and grim. It takes focus, so don’t run it while you’re typing elsewhere.

Timing

bench/m0.sh [FILE] [RUNS]

Measures cold and warm opens to the first frame. The targets are under 50 ms warm and under 400 ms cold (p95). It stops any running n0te-app, including your own service, so close what you’re working on first.

How the code is laid out

Path	Job
`src/main.rs`	`n0te`, the client: std only, never links GTK; sends arguments to the service, starts it if needed, runs `--setup` and `--complete`
`src/lib.rs`	shared, std only: finding the vault (`obsidian.rs`), settings (`config.rs`), the runtime folder (`runtime.rs`), Omarchy wiring (`setup.rs`)
`src/bin/n0te-app/main.rs`	the GTK app: the service, arguments, prewarming, `--check`, `--bench`
`src/bin/n0te-app/window.rs`	one window: history, palette, find, keys, status line, editing, saving, file watching, undo
`src/bin/n0te-app/render.rs`	markdown to a text buffer, with blocks and their source ranges, links, headings and folds
`src/bin/n0te-app/edit.rs`	no GTK: splicing, atomic writes, the three-way merge, undo history, list helpers
`src/bin/n0te-app/view.rs`	the text view: boxes, the edit box, the block tick, the focus veil, line numbers
`src/bin/n0te-app/table.rs`	tables, measured and wrapped to the window
`src/bin/n0te-app/highlight.rs`	tree-sitter and the small built-in highlighters
`src/bin/n0te-app/vault.rs`	the note index, wikilinks, daily notes, templates
`src/bin/n0te-app/theme.rs`	Omarchy colors and live reload
`packaging/`	the Hyprland file, desktop entry and theme template; the release tarball (`release.sh`, `install.sh`, `licenses.py`) and the AUR package draft
`site/`	this website and these docs

CLAUDE.md at the repository’s root has the working notes: design decisions, how editing works inside, and the gotchas already paid for. Read it before a big change.

These docs

The docs are an mdBook in site/docs/, and the front page is plain HTML in site/www/. To preview both:

site/build.sh --serve      # builds into site/dist and serves it on localhost

A change to how n0te behaves should update its page in the same commit. Releases and the site deploy from a maintainer’s machine with site/deploy.sh; see site/README.md.

Keyboard shortcuts