# outl

> outl is a local-first outliner where markdown is the source of truth and sync is provably correct via a tree-CRDT. Built in Rust. Open source (MIT). Inspired by Roam Research and Logseq, fixes their sync and file-format trade-offs.

## What outl is

- A daily-driver outliner with vim-style TUI, journal-first, slash commands, fuzzy switcher.
- Plain CommonMark on disk — no `id::` lines, no UUIDs, no HTML comments. Block IDs live in a separate `.foo.outl` JSON sidecar.
- Code blocks that execute inside notes — Python, Lisp, JavaScript, Lua, Rust — with idempotent `> result:` subblocks and source-hash caching.
- A tree-CRDT implementation following Kleppmann et al. 2022 with five formal guarantees backed by property tests.
- Importers for Logseq and Roam Research that strip metadata and resolve block refs.

## Status (v0.1.0, May 2026)

Single-device editor, daily-driver-ready. CRDT algorithm and op-log infrastructure are in. P2P transport via iroh is phase 2 of the roadmap.

## Core differentiators

- **Markdown stays clean.** Unlike Logseq, outl never writes UUIDs into your `.md`.
- **Sync that can't lose data.** Unlike Roam (last-write-wins) or Logseq Sync (rsync-flavored), outl's tree-CRDT provides strong eventual consistency.
- **Open source, native binary.** Unlike Roam (proprietary, cloud) or Obsidian (proprietary, Electron), outl is MIT-licensed and ships as a Rust binary.
- **Code blocks that actually run.** Multi-language code execution as a first-class feature, not a plugin.

## Pages

- [Home](https://outl.app/): product overview, terminal demo, comparison table, FAQ, install.
- [Manifesto: sync, done right](https://outl.app/sync): long-form explanation of why Roam, Logseq, and Git fail at sync, and how outl's tree-CRDT solves it. Seven acts covering the failure modes, the architecture, the hard case, the five formal guarantees, the trade-offs.
- [Docs](https://outl.app/docs): full documentation hub, mirrored live from github.com/avelino/outl/docs via git submodule. Includes architecture, CRDT walkthrough, markdown dialect, TUI manual, theming, roadmap, getting started, tutorial.
- [Code execution](https://outl.app/code): showcase of executable code blocks in Python, Lisp, JavaScript, Lua and Rust. WASM sandbox details, auto-run property, source-hash caching, comparison to Jupyter/Notion/Dataview/Observable.
- [Format spec](https://outl.app/format): the markdown dialect outl reads and writes. Properties (`title::`, `icon::`, `tags::`, `auto-run::`), references (`[[page]]`, `((block-id))`, `#tag`), code fences, 3-level matching algorithm.
- [Import / migration](https://outl.app/import): step-by-step migration from Logseq, Roam Research and Obsidian. Before/after examples, troubleshooting, what carries over.
- [Alternatives](https://outl.app/vs/roam) / [vs Logseq](https://outl.app/vs/logseq) / [vs Obsidian](https://outl.app/vs/obsidian): honest deep-dive comparisons. What each competitor got right, where it breaks, the killer scenario it loses, and how outl resolves it.
- [Blog](https://outl.app/blog) — release notes and deep-dives. Includes [Announcing outl 0.1.0](https://outl.app/blog/announcing-outl-0-1-0).

## Docs (on GitHub)

- [Sync algorithm walkthrough](https://github.com/avelino/outl/blob/main/docs/sync.md): the manifesto's full markdown source.
- [Tree CRDT walkthrough with code](https://github.com/avelino/outl/blob/main/docs/crdt.md): the algorithm with Rust code, worked examples, and invariants.
- [Markdown dialect](https://github.com/avelino/outl/blob/main/docs/markdown-format.md): how `title::`, `icon::`, `tags::`, `[[refs]]`, `((block-id))` work and how external edits are reconciled.
- [Architecture](https://github.com/avelino/outl/blob/main/docs/architecture.md): crate boundaries and on-disk layout.
- [Storage trait](https://github.com/avelino/outl/blob/main/docs/storage.md): pluggable storage backends.
- [Roadmap](https://github.com/avelino/outl/blob/main/docs/roadmap.md): six phases — single-device → P2P sync → queries → plugins → desktop → mobile.
- [Tutorial](https://github.com/avelino/outl/blob/main/docs/tutorial.md): walkthrough for new users.
- [TUI manual](https://github.com/avelino/outl/blob/main/docs/tui.md): keybindings, modes, slash commands.
- [Theming](https://github.com/avelino/outl/blob/main/docs/theming.md): 11 built-in themes + custom themes.

## Install

- `brew install outl` (homebrew formula in progress)
- `cargo install outl` (works today)
- Build from source: `git clone https://github.com/avelino/outl && cd outl && cargo build --release`

## Repo

- Source: https://github.com/avelino/outl
- License: MIT
- Language: Rust
- Author: Avelino (https://avelino.run)