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 guide 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. See the editor setup. -
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. See the web guide.
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 luzzle 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.jobsshared job definitions@luzzle/web.themeshared css styles and theme types@luzzle/web.piecesshared piece definitions and helpers@luzzle/web.templatesshared template contracts and canonical built-in sources
Start with the guides: your archive, the CLI, editor support and the web stack. Working on Luzzle itself? See development.