Skip to content
Cortex

Vault, Editor, and Workspace APIs

Use vault files, the active editor, fold providers, and workspace tabs from a plugin.

1 min readEdit on GitHub

Handlers receive ctx. These APIs require runtime permissions in manifest.permissions.

Vault Paths#

Vault APIs use vault-relative paths with forward slashes:

ts
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#

ts
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#

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

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

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

Search docs

Search Cortex documentation pages and headings.