README
¶
snorg
Supernote organizer: ingests Supernote .note files into a plaintext,
machine-readable, VCS-friendly archive for later retrieval, analysis and export.
The .note binary format is handled by shelling out to
supernote-tool (must be on PATH);
the org-mode export filter shells out to pandoc. Written in Go.
Quick start
Prerequisites: supernote-tool on
PATH (required for ingest); pandoc only if you export to org-mode.
Install the CLI (puts snorg on your PATH via $GOBIN/$GOPATH/bin):
go install github.com/jdlugosz963/snorg/cmd/snorg@latest
# or, from a clone: go build -o snorg ./cmd/snorg
Then archive a note and read it back:
snorg -a ~/notes/archive ingest ~/supernote/Note/idea.note # register (a dir works too)
snorg -a ~/notes/archive list # FILE_IDs, one per line
snorg -a ~/notes/archive retrieve <FILE_ID> # assembled note as JSON
# Optional AI pass: transcribe pages with a vision LLM (needs a provider config).
snorg -a ~/notes/archive query all | \
snorg -c config.yaml -a ~/notes/archive analyze # skips unchanged pages
# Export through a template (see examples/config.yaml).
snorg -c examples/config.yaml -a ~/notes/archive export <FILE_ID>
Usage
Global flags and the archive path come first, then the command; the config
(<archive>/config.yaml, overridden by -c files) is loaded once and shared:
snorg -a <archive> ingest <file.note> # register a note (dir works too)
snorg -a <archive> list # list FILE_IDs
snorg -a <archive> retrieve <FILE_ID> # assembled note as JSON
snorg -a <archive> query all # PAGEIDs of matching pages
snorg -a <archive> query all | \
snorg -c cfg.yaml -a <archive> analyze # LLM analysis (skips unchanged pages)
snorg -c examples/config.yaml -a <archive> export <FILE_ID> # render a template
Archive layout: <archive>/<FILE_ID>/{note.json,<PAGEID>.json,<PAGEID>.md,<PAGEID>.svg,backgrounds/}.
Shell completion
snorg ships completion scripts; source the right one for your shell:
# .bashrc
source <(snorg completion bash)
# .zshrc
source <(snorg completion zsh)
# fish
snorg completion fish > ~/.config/fish/completions/snorg.fish
# Powershell: write `snorg completion powershell` to a file on your autocomplete path and run it.
Example: Emacs / denote client
examples/emacs/ is a worked end-to-end use case: it exports a
snorg archive into a human-readable, organized form — one org note per archived
note under a denote directory, with
cross-note links resolving inside Emacs. It
pairs an org-mode export template (examples/emacs/orgmode.yaml) with snorg.el,
which drives the snorg CLI to import notes as denote org files and adds org links
that open a page's SVG or jump between notes. See examples/emacs/README.md.
More
See docs/ for principles, architecture, the .note format, configuration and
the read contract; examples/config.yaml for an annotated config with a Markdown
export template.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
snorg
command
Command snorg is the supernote-organizer CLI.
|
Command snorg is the supernote-organizer CLI. |
|
internal
|
|
|
analyze
Package analyze runs vision-LLM analysis on a single archived page: it rasterizes the page SVG, crops each title/link region, transcribes them and the whole page, and writes the result into the page's <PAGEID>.json (per-region names, custom fields) and <PAGEID>.md sidecar (the transcribed content).
|
Package analyze runs vision-LLM analysis on a single archived page: it rasterizes the page SVG, crops each title/link region, transcribes them and the whole page, and writes the result into the page's <PAGEID>.json (per-region names, custom fields) and <PAGEID>.md sidecar (the transcribed content). |
|
archive
Package archive owns the on-disk plaintext layout of organized notes:
|
Package archive owns the on-disk plaintext layout of organized notes: |
|
config
Package config loads snorg's runtime configuration: provider credentials, analysis prompts, ingest SVG toggles and the export template.
|
Package config loads snorg's runtime configuration: provider credentials, analysis prompts, ingest SVG toggles and the export template. |
|
export
Package export renders an assembled note (retrieve.NoteView) through a single user-supplied template, producing arbitrary text output (org-mode, markdown, html, …).
|
Package export renders an assembled note (retrieve.NoteView) through a single user-supplied template, producing arbitrary text output (org-mode, markdown, html, …). |
|
ingest
Package ingest orchestrates registering .note files into an archive: read the domain model from a snote.Source, render all pages to SVG in one pass, and write everything through the archive store.
|
Package ingest orchestrates registering .note files into an archive: read the domain model from a snote.Source, render all pages to SVG in one pass, and write everything through the archive store. |
|
query
Package query is the read-only filter side of the archive: it walks every note/page and selects the pages matching a predicate over their stored metadata (star, keywords, note membership, analysis state, ...).
|
Package query is the read-only filter side of the archive: it walks every note/page and selects the pages matching a predicate over their stored metadata (star, keywords, note membership, analysis state, ...). |
|
retrieve
Package retrieve is the platform-agnostic read contract over an archive: it assembles the per-note storage files (note.json + each <PAGEID>.json) into a single denormalized NoteView that any external tool can consume to build a human-readable form (e.g.
|
Package retrieve is the platform-agnostic read contract over an archive: it assembles the per-note storage files (note.json + each <PAGEID>.json) into a single denormalized NoteView that any external tool can consume to build a human-readable form (e.g. |
|
snote
Package snote defines the device-agnostic domain model for a Supernote note and the Source contract for reading/rendering one.
|
Package snote defines the device-agnostic domain model for a Supernote note and the Source contract for reading/rendering one. |
|
snote/sntool
Package sntool implements snote.Source by shelling out to the `supernote-tool` CLI (supernotelib).
|
Package sntool implements snote.Source by shelling out to the `supernote-tool` CLI (supernotelib). |