90 lines
3.6 KiB
Markdown
90 lines
3.6 KiB
Markdown
# Luzzle 🧩
|
||
|
||
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.
|
||
|
||
## What is a digital garden? 📁
|
||
|
||
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. 📝✨
|
||
|
||
## Why Text? 🧠
|
||
|
||
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.
|
||
|
||
## Three Ways to Use Luzzle 🚀
|
||
|
||
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](./docs/cli.md) 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](./docs/lsp.md).
|
||
|
||
- **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](./docs/web/README.md).
|
||
|
||
## The Spec 🏗️
|
||
|
||
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 (like
|
||
`book` or `film`). 📂
|
||
- 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. 🚧
|
||
|
||
## The Monorepo 📦
|
||
|
||
This ecosystem contains a few projects to manage a luzzle archive:
|
||
|
||
- `@luzzle/core` the specification implementation 🫀
|
||
- `@luzzle/cli` the terminal companion for managing pieces 💻
|
||
- `@luzzle/lsp` auto-complete in your editor while editing pieces ✏️
|
||
- `@luzzle/web` web app for browsing, editing and publishing pieces 🔎
|
||
|
||
a set of services to power a luzzle web app:
|
||
|
||
- `@luzzle/web.worker` jobs for publishing and previewing 👷
|
||
- `@luzzle/web.proxy` a caching layer for @luzzle/web 🚀
|
||
- `@luzzle/web.lsp` websocket server for the editor's luzzle lsp 💂
|
||
|
||
and some shared packages used for the web project:
|
||
|
||
- `@luzzle/web.config` shared configuration schemas for the web stack ⚙️
|
||
- `@luzzle/web.jobs` shared job definitions
|
||
- `@luzzle/web.theme` shared css styles and theme types
|
||
- `@luzzle/web.pieces` shared piece definitions and helpers
|
||
- `@luzzle/web.templates` shared template contracts and canonical built-in sources
|
||
|
||
## Documentation 📖
|
||
|
||
Start with [the guides](./docs/README.md): your archive, the CLI, editor support
|
||
and the web stack. Working on Luzzle itself? See [development](./docs/development.md).
|