Repository navigation
Releases: martintrojer/mdroots
Release list
v0.4.0
Full Changelog: v0.3.2...v0.4.0
v0.3.2
v0.3.1
v0.3.0
v0.2.10
v0.2.9
mdroots 0.2.8: AND and parentheses in tag expressions
Tag expressions in mdroots notes -t now take AND and parentheses.
mdroots notes -t "career AND NOT projects"
mdroots notes -t "(xt26 OR career), NOT AI-AUTHORED"
mdroots notes -t "NOT (draft, wip)"ANDworks like the comma.ORand|bind tighter, andNOTand-tightest, as in zk.- Parentheses group sub-expressions, nested as deep as you like.
a OR (NOT b)is allowed; a barea OR NOT bis still refused, as zk refuses it. - Fixed: in 0.2.7,
ANDand parentheses were read as part of tag names, so these queries silently matched nothing and exited 0. - Syntax errors (an unclosed
(, a stray), a danglingAND) are now usage errors with exit 2, and name their column:mdroots: -t: column 6: expected ). - Whitespace: keywords may be separated by tabs as well as spaces.
- Names: lowercase
and/or/not, and names likeANDROIDorNOTES, stay tag names.
Install: cargo install mdroots-cli, or download a binary below (macOS on Apple silicon, Linux x86_64).
mdroots 0.2.7: first public release
The first public release of mdroots: a markdown and org language server, CLI and Rust library that works the moment you open a note.
No init step, no config, no root markers. mdroots finds the notebook a file belongs to, answers for that file at once, indexes the rest in the background, and keeps the index in your user cache dir, so the next editor on the same notebook starts warm. It reads the link styles you already use: zk, Obsidian, marksman, Foam, Dendron, Logseq, org-mode and plain relative paths, mixed in one notebook if that's how you write.
Highlights
- About 10 ms to the first answer for the note you opened, at any notebook size. Notebook-wide answers follow once the index is up.
- One cache, shared by every editor. The first process on a notebook writes it; the others read. Unchanged notes are never re-read.
- Zero config. Roots and conventions are detected. Settings you already made in zk or Obsidian are honoured, and
mdroots roots NOTEshows each setting with its source. - Safe on big trees. It never walks remote, virtual or oversized trees; it falls back to the folders you actually open.
- A library first. The server, the CLI and embedders such as ramble share one Rust API.
In the editor (mdroots lsp)
Go to definition (links, headings, path:line code mentions), references and backlinks, hover previews, document and workspace symbols, completion of notes, headings, paths and tags, rename with link updates, broken-link and broken-anchor diagnostics, folding, code lenses, document links, extract-note, and live updates from a file watcher. A Neovim 0.12+ config is in editors/nvim/.
On the command line
mdroots check notes/ # broken links and anchors; exit 1 on problems
mdroots notes --orphan # notes nothing links to
mdroots notes -t 'project, NOT done' -s modified- -n 10
mdroots notes --missing-backlink -f json
mdroots tags --sort count
mdroots search 'rust async' notes/
mdroots backlinks notes/a.md
mdroots roots notes/a.md # the root it picked, why, and its settingsmdroots notes takes zk list's filters (tag expressions, created and modified dates, --orphan, --missing-backlink, --link-to, --linked-by, --related, --sort, --limit) and prints path, tsv, json or jsonl, with -0 for xargs -0.
Compared with zk and marksman
10,000-note synthetic notebook, time from server start, median of 5 runs (method, caveats and how to reproduce):
| mdroots (warm) | mdroots (cold) | zk (indexed) | marksman | |
|---|---|---|---|---|
| first answer (go to definition) | 9 ms | 28 ms | 210 ms | 4.9 s |
| full note completion | 404 ms | 2.3 s | 294 ms | 4.9 s |
| broken-link diagnostic | 380 ms | 2.3 s | 227 ms | 5.5 s |
| memory (phys_footprint) | 92 MB | 92 MB | 54 MB | 320 MB |
| setup | none | none | zk index: 112 s |
none |
Once zk index has run, zk is faster on notebook-wide answers and lighter at this size. mdroots needs no index step and answers the open note first. At 1,000 notes mdroots uses the least memory: 17 MB, against 24 MB for zk and 105 MB for marksman.
What it is not
- Not a note manager. It reads notes and answers questions about them; it never creates notes or fills templates. Renames and extract-note come back as edits for your editor to apply.
- Not a daemon. It runs inside each editor or command.
- Not a tenant in your notes. Nothing is written into your trees. Tool configs are read when their marker is present, and are never required or written.
Install
cargo install mdroots-cli # the mdroots binary: server and CLI
cargo add mdroots # the libraryOr download a binary below (macOS on Apple silicon, Linux x86_64), check it against its .sha256, and put mdroots on your PATH.
Known limits
- Memory at 10k notes is 92 MB per process, above the project's 35 MB target. Smaller notebooks are well under it.
- One request at a time: a request already running is not interrupted.
- Validated mostly on synthetic notebooks and two real vaults; many-editor memory and cold-cache rates on network filesystems are not measured yet.
The full list is in the roadmap.
Docs
README · how roots are found · the index, links and resolution · library, CLI and server · design decisions · changelog
MIT licensed.