LogoNotyra Docs
Plugins

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.

MethodBehavior
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.

MethodResult / 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

MethodPermissionBehavior
clipboard.readText() / writeText(text)clipboardRead/write the system text clipboard
shell.openExternal(url)shell:openExternalOpen http, https or mailto using the system handler
network.fetch(url, init?)networkHTTP/HTTPS to consented destinations; see below
notes.listRootFolders()notes:readAbsolute paths of registered roots
notes.list(rootFolder)notes:readNote metadata within a registered root
notes.read(path)notes:read{ path, body, frontMatter }
notes.create(input)notes:writeCreate a note and return its saved path
notes.update(path, { body, frontMatter })notes:writeUpdate body and Front Matter
notes.rename(path, newTitle)notes:writeChange title/filename and return the saved path; existing target names are rejected
notes.move(rootFolder, path, targetFolder)notes:writeReturn the destination path, adding the smallest unused numeric suffix for a duplicate name
notes.delete(path)notes:writeAsk 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.