Skip to content

mdroots 0.2.7: first public release

Choose a tag to compare

View all tags
@github-actions github-actions released this 10 Oct 12:46
· 92 commits to main since this release
v0.2.7
02cc74e

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 NOTE shows 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 settings

mdroots 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 library

Or 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.

Assets 6
Loading