Vault, Editor, and Workspace APIs
Use vault files, the active editor, fold providers, and workspace tabs from a plugin.
Handlers receive ctx. These APIs require runtime permissions in manifest.permissions.
Vault Paths#
Vault APIs use vault-relative paths with forward slashes:
const content = await ctx.vault.readFile("Projects/Plan.md")await ctx.vault.writeFile("Projects/Plan.md", `${content}\n\nUpdated by plugin.`)Do not pass absolute paths, .., or platform-specific separators. The host validates paths before
touching the filesystem. Reads need vault:read, writes vault:write, deletes vault:delete.
Vault Events#
activation: "startup",activate(ctx) { ctx.vault.onFileEvent((event) => { if (event.path.endsWith(".md")) console.log(event.type, event.path) })},Requires vault:watch. Events carry create | modify | delete | rename and a vault-relative path.
The subscription is disposed automatically when the plugin is disabled.
Editor Reads and Writes#
const filePath = ctx.editor.getActiveFilePath()const content = ctx.editor.getActiveFileContent()if (filePath && content !== null) ctx.editor.replaceSelection("**important**")Use editor:read for reads and editor:write for insertAtCursor / replaceSelection.
Editor Extensions#
contributes.editorExtensions(ctx) returns host editor extensions (CodeMirror on desktop and
mobile). It runs when the plugin is enabled, and the result applies to every open editor. Keep
@codemirror/state and @codemirror/view external in your build; the host provides them when the
bundle imports them.
Fold Providers#
Fold providers are portable and line-based; they do not expose CodeMirror or DOM objects.
contributes: { foldProviders: [ { id: "spoiler-blocks", label: "Spoiler blocks", getFoldRange: (context) => { if (context.lineText !== ":::spoiler") return null for (let line = context.lineNumber + 1; line <= context.lineCount; line += 1) { if (context.getLine(line) === ":::") return { toLine: line, placeholder: "spoiler" } } return null }, }, ],},Workspace Tabs#
All workspace methods require workspace:tabs.
ctx.workspace.openFile("Projects/Plan.md", { target: "right", newTab: true })ctx.workspace.openView("dashboard", { target: "active" })ctx.workspace.openMarkdownTab({ title: "Plugin Report", content: "# Report\n\nGenerated." })openView accepts only this plugin's declared view ids. openMarkdownTab shows generated Markdown
in an ephemeral tab without writing to the vault.