A notes screen for lich, and the reference example of a lich extension. Read it to see how an extension is put together, then copy what you need into your own.
- Lists the Markdown notes of a folder you choose (a vault), newest first. Sub-folders are included and folders whose name starts with a dot are skipped.
- Filters the list as you type, by title and by content.
- Shows the selected note three ways: Preview renders it, Split puts the Markdown source beside the rendered note and updates it as you type, Edit shows the source alone. Save writes the file, and saving from Edit goes back to the preview.
- Creates a new note as
Untitled N.md.
| Key | Does |
|---|---|
/ |
Puts the keyboard in the search field |
Ctrl+N |
New note |
Ctrl+S |
Save, in Split or Edit |
Esc |
Hands the keyboard back, so / works again |
A note you changed is saved when you open another one, so nothing typed is lost by clicking away.
The first time you open the screen it asks for the vault's path. The folder button beside the search field changes it later. The interface follows lich's language, in English and Brazilian Portuguese.
lich lists extensions in Settings › Extensions. Open the Notes screen from the button it adds to the top bar.
Choose From GitHub, paste https://github.com/lichdotdev/lich-notes and confirm. lich downloads the
archive of the latest release built for your system and checks it against the release's checksums.
Build it, and put the three things lich reads in a folder of their own:
go build -o lich-notes .
mkdir -p /tmp/lich-notes
cp -R manifest.json lich-notes locales /tmp/lich-notes/Choose From a folder and pick /tmp/lich-notes. lich copies the folder, so you can delete it afterwards.
On Windows build lich-notes.exe and name it in the manifest's executable.
lich reads a linked folder too, which is how you run the code you are editing. Link this checkout into the extensions directory under the extension's id:
go build -o lich-notes .
ln -s "$PWD" ~/.config/lich/extensions/lich-notesThe directory is ~/Library/Application Support/lich/extensions on macOS and %AppData%\lich\extensions on
Windows. A lich run with LICH_DEV set reads extensions-dev instead. Restart lich to pick the link up.
After a change, build again and restart lich. What the extension prints to stderr goes to lich's log.
go vet ./... && go test ./...An extension is a program lich starts and talks to over JSON lines on stdin and stdout. It does not draw: it
sends a tree of components and lich draws them. The Go package
github.com/lichdotdev/lich/extension has the
types, so no JSON is written by hand here.
| File | Holds |
|---|---|
manifest.json |
What lich reads before starting the program: its id, the executable, the screen it adds |
locales/<tag>/ |
The translations. extension.json names the extension and its screen, notes.json is the screen's own text |
main.go |
Start-up: load the catalogs and the settings, then answer lich's messages until it closes stdin |
app.go |
The state of the screen and what each message from lich changes in it |
view.go |
The component tree built from that state, and the keyboard shortcuts |
vault.go |
The notes on disk: list, search, read, save, create. Knows nothing about lich |
settings.go |
The vault's path, kept in the data directory lich gives the extension |
release.sh |
Builds the archives and checksums.txt a release carries |
The loop in three steps, which every extension repeats:
- lich sends a message: the screen opened, a control fired the handler the tree named for it, or the language changed.
app.handlechanges the state.app.rendersends the whole tree again. lich keeps what the person typed and where they scrolled, as long as a node keeps its key.
Things here that are easy to get wrong in your own:
- Save into the data directory, not beside the executable: an update replaces the extension's folder.
lich passes the path in
LICH_EXTENSION_DATA. - Send
focusafter the render that draws the field. lich drops a focus for a field it has not drawn. - Key a field by what it edits. The editor here is keyed by the note's path, so one note's caret never lands in another.
- Check paths that come back in events. A row's handler carries the note's path, and
vault.gorefuses one that leaves the vault.
The full contract is in Writing a lich extension.
Bump version in manifest.json, commit, then push a tag of the same version:
git tag v0.1.0 && git push origin v0.1.0.github/workflows/release.yml runs the tests and release.sh, and publishes
lich-notes_<os>_<arch>.tar.gz for Linux, macOS and Windows on amd64 and arm64 with checksums.txt, the
shape lich installs from. ./release.sh v0.1.0 builds the same files into dist/ on your machine.
AGPL-3.0, the same as lich.
