API reference
All Plugin API extension points and methods
Use import { notyra } from '@notyra/plugin-api' to obtain the plugin-specific API. pluginId is the manifest name; apiVersion is the Notyra version. modules exposes the host's shared React, ReactDOM, CodeMirror and Lezer instances. The canonical types are in the app's src/shared/plugin/api.ts; the independent @notyra/plugin-api repository distributes the matching version.
Registration APIs
These methods return a Disposable. Calling dispose() repeatedly is safe. The host removes remaining registrations at stop; registrations after stop fail with pluginNotActive.
| Method | Behavior |
|---|---|
styles.add(css) | Add CSS to this window, managed in a plugin-specific style element |
sidePanel.registerView({ id, title, icon, render }) | Register a panel view; icon is SVG text. render(container) may return a cleanup function |
markdown.registerRemarkPlugin(pluggable) | Transform Markdown AST after builtin remark plugins |
markdown.registerRehypePlugin(pluggable) | Transform HTML AST after builtin image/Mermaid processing and before highlighting |
editor.registerExtension(extension) | Append a CodeMirror extension, validated before registration |
commands.register({ id, title, run }) | Register a synchronous or asynchronous command |
toolbar.addButton({ command, icon, tooltip }) | Add a button that invokes a registered command |
keymaps.add({ key, command }) | Add a CodeMirror-style key. Mod is Meta on macOS and Ctrl elsewhere |
events.onActiveNoteChange(listener) | Subscribe to note switching and body changes; no permission required |
settings.onDidChange(listener) | Subscribe to this plugin's settings |
Local view and command IDs become ${pluginId}:${id}. Builtin shortcuts win; earlier plugins win conflicts between plugins. Registering a command does not create a general command-list UI: expose it through a toolbar button, keymap, your panel or commands.execute(id).
A Markdown pluggable is a function or [function, ...arguments]. Plugins run in load order, preserving registration order within each plugin. The same extensions apply to preview and PDF/HTML export. A failing plugin's Markdown extensions are excluded for the session; preview keeps the last successful HTML. Exclusion does not immediately regenerate preview, but takes effect on the next edit or other generation trigger.
Note events, settings and execution
type ActiveNoteEvent = {
type: 'switched' | 'changed'
note: { path: string; title: string; rootFolder: string; body: string } | null
windowKind: 'main' | 'note'
}A switch is delivered after the note body is loaded. Changes are briefly debounced. A newly subscribing plugin receives the current note as a switched event. note: null means no note is selected.
| Method | Result / behavior |
|---|---|
settings.get<T>(key) | A declared setting, falling back to its default for missing or invalid stored data |
settings.getAll() | An object containing declared settings only |
settings.onDidChange(listener) | Subscribe to the resolved values object. Settings are saved from the settings UI |
editor.scrollToLine(line) | One-based; clamps to document bounds. Returns false if no editor is available |
commands.execute(id) | Invoke a registered command and return Promise<void> |
The template and ToC contain complete implementations.
Permission-gated APIs
| Method | Permission | Behavior |
|---|---|---|
clipboard.readText() / writeText(text) | clipboard | Read/write the system text clipboard |
shell.openExternal(url) | shell:openExternal | Open http, https or mailto using the system handler |
network.fetch(url, init?) | network | HTTP/HTTPS to consented destinations; see below |
notes.listRootFolders() | notes:read | Absolute paths of registered roots |
notes.list(rootFolder) | notes:read | Note metadata within a registered root |
notes.read(path) | notes:read | { path, body, frontMatter } |
notes.create(input) | notes:write | Create a note and return its saved path |
notes.update(path, { body, frontMatter }) | notes:write | Update body and Front Matter |
notes.rename(path, newTitle) | notes:write | Change title/filename and return the saved path; existing target names are rejected |
notes.move(rootFolder, path, targetFolder) | notes:write | Return the destination path, adding the smallest unused numeric suffix for a duplicate name |
notes.delete(path) | notes:write | Ask the user to confirm the plugin and note names, then delete; cancellation rejects with deleteRejected |
The create input is { rootFolder, title, folder?, body?, frontMatter? }. folder and the move targetFolder are relative to the selected root. Note operations stay within registered roots; other paths fail with outOfScope. Creation/moving uses <base>.md or <base>-N.md without overwriting existing files. notes:write does not imply notes:read; an example that lists roots declares both.
network.fetch accepts { method?, headers?: Record<string,string>, body?: string | ArrayBuffer | Uint8Array }. Its response has status, ok, url, headers and asynchronous text(), json<T>(), arrayBuffer() methods. It does not implement every browser fetch option.
Await API calls and inspect error.kind on failure. See permissions and networking and the runnable examples.