Build plugins for notesy

Build plugins for notesy: small Rune scripts that add panels, commands and more, and do only what the user allows.

The API

Basics

  • log: Lines for its log on the Plugins page
  • events: Hearing what happens, and every event
  • commands: Adding commands, and running notesy's
  • store: Keeping its own data
  • settings: Reading its settings
  • secrets: Keys and tokens, in the system keychain

Notes and files

  • notes: Reading and changing the vault's notes
  • editor: The note in front
  • files: A folder of its own
  • links: Opening pages in the browser
  • clipboard: Copying and pasting

Interface

  • view: What panels, tabs and sections show
  • panels: Adding side panels and tabs
  • sections: Sidebar sections
  • menus: Items in notesy's right-click menus
  • status: Status bar items
  • notices: Notices
  • dialogs: Asking in a dialog, notesy's kinds or its own
  • cards: Its part of the tree's hover cards
  • boards: Boards' cards and arrows, and kinds of card of its own
  • blocks: Drawing its fenced blocks
  • icons: Drawing its own icons

The web

  • net: Requests to the sites it names
  • accounts: Signing in to a service

Data and helpers

  • json: Reading and writing JSON
  • toml: Reading and writing TOML
  • yaml: Reading and writing YAML, and a note's front matter
  • time: Now, written in the user's time zone, dates read, how long ago
  • math: Trigonometry and the like, for drawing
  • names: Notesy's names as enums

Tools

  • preview: Its own screens for notesy preview
  • perf: Timing its own work

How plugins work

A notesy plugin is a folder with a plugin.toml in it. Some plugins only add looks (themes, icon packs, syntax, colors, code languages): notesy reads what they declare and does it itself, and they run nothing. Others run a script, written in Rune, which notesy runs in a sandbox of its own after the user has said yes to what the plugin asks for.

Plugins are a walled garden. A plugin does only what its manifest declares and the user approved; it reaches only the web hosts it names, through notesy's own fetch; it hears only the events its permissions cover. A script has no files, sockets, processes or native code, only notesy's modules.

#A first plugin

Make a folder called you.saves anywhere you like, with two files, then load it: Settings, Plugins, "Load a plugin folder". notesy links it in as it is (nothing to pack) and reloads it each time you save.

plugin.toml:

tomlid = "you.saves"
name = "Saves"
version = "0.1.0"
author = "You"
license = "MIT"
main = "main.rn"
permissions = ["notes.read"]

main.rn:

rustuse notesy::{events, log, store, Event};

pub fn ready() {
    events::on(Event::NoteSaved, |event| {
        let saves = store::get("saves").unwrap_or(0) + 1;
        store::set("saves", saves);
        log::info(`${event.path} saved; ${saves} saves so far`);
    });
}

Open the Plugins page: the plugin asks to read your notes. Say yes, and each time a note is saved, its log (under it on the Plugins page) says so.

#An example to start from

examples/plugins/example.tasks is a whole plugin: a Tasks panel beside the note (its - [ ] lines, what's left and done), a status bar item saying how many are left, and a command. Copy its folder into your plugins folder to try it.

#Folder layout

plugins/
  you.saves/          one folder per plugin, named after its id
    plugin.toml
    main.rn           its script, when it has one
  grants.toml         what the user allowed each plugin (notesy's own)
plugin-data/
  you.saves/
    store.toml        its settings' values and what it keeps (see api/store.md)

plugin-data is kept apart from plugins so updating a plugin keeps its data.

Every page