Luzzle is a text-first approach for managing your digital garden. It enables a folder of Markdown files to be used as a database for web, desktop or mobile projects.
a database which you own and control. in real time.
no takeout needed.
Think of it as a personal library for anything you want to record. books you've read, gear in your inventory, contacts in your address book or all the poems you've written.
Instead of being trapped in a spreadsheet or a proprietary app, these records
live in an archive folder. Each piece is just a Markdown file representing
a single item. 📝✨
Plain text is the best (hands down!) format for long-term preservation and ownership. It’s the original WYSIWYG interface: human-readable, machine-writable, and it won't hold your data hostage.
By using text, we get to stand on the shoulders of giants. We don't need to reinvent search, syncing, or versioning when we can just use the Unix tools that have already solved those problems for decades.
Depending on how you want to interact with your garden, Luzzle offers three entry points. Use one, two or all three. It's a buffet!
-
The CLI (
@luzzle/cli) — Just get a database. A command-line companion to quickly initialize and sync your Markdown archive into a local SQLite index. Great if you just want to run queries or plug Luzzle into your own scripts. See the CLI README for usage and commands. -
The LSP (
@luzzle/lsp) — Schema-aware editing. Get autocomplete, schema validation, and diagnostics inside your editor (like Neovim) as you edit your piece frontmatter. It hooks into any LSP-compatible editor. -
The Web Stack (
@luzzle/web) — Digital garden on the web. A responsive SvelteKit explorer/admin interface, a background worker queue to sync and transform assets, and a caching reverse proxy. It runs via Docker Compose—making it the heaviest to deploy, but also the most complete.
Luzzle is both a set of rules and the code to run them.
- Your archive is just a root folder.
- JSON schemas live in
.luzzle/schemas/to define your piece types (likebookorfilm). 📂 - Attachments like images and archives live in an
.assets/folder. 🖼️ - Pieces use a simple naming convention:
name.piece-type.md(e.g.,dune.book.md).
The formal specification is still evolving alongside the codebase. 🚧
This ecosystem contains a few projects to manage a luzzlel archive:
@luzzle/corethe specification implementation 🫀@luzzle/clithe terminal companion for managing pieces 💻@luzzle/lspauto-complete in your editor while editing pieces ✏️@luzzle/webweb app for browsing, editing and publishing pieces 🔎
a set of services to power a luzzle web app:
@luzzle/web.workerjobs for publishing and previewing 👷@luzzle/web.proxya caching layer for @luzzle/web 🚀@luzzle/web.lspwebsocket server for the editor's luzzle lsp 💂
and some shared packages used for the web project:
@luzzle/web.configshared configuration schemas for the web stack ⚙️@luzzle/web.jobshared job definitions@luzzle/web.themeshared css styles and theme types@luzzle/web.piecesshared piece definitions and helpers
If you'd like to contribute or understand the design principles behind the codebase, check out the Development Philosophy & Standards.
If you are working on the web stack, please also review the Web Development Standards (such as offloading intensive work to the worker queue and leveraging theme variables for styling consistency).