Plugin Development

Vault, Editor, and Workspace APIs

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

On this page

Use these APIs when a plugin needs user files, the active editor, or workspace tabs.

Vault Paths

Vault APIs use vault-relative paths with forward slashes:

const content = await this.api.vault.readFile("Projects/Plan.md")await this.api.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.

Vault Events

const disposable = this.api.vault.onFileEvent((event) => {	if (event.path.endsWith(".md")) {		console.log(event.type, event.path)	}})

Declare vault:watch. Dispose subscriptions you create manually.

Editor Reads and Writes

const filePath = this.api.editor.getActiveFilePath()const content = this.api.editor.getActiveFileContent()if (filePath && content !== null) {	this.api.editor.replaceSelection("**important**")}

Use editor:read for reads and editor:write for writes. Editor paths are still vault-relative when available.

Fold Providers

Fold providers are portable and line-based. They do not expose CodeMirror or DOM objects.

this.registerFoldProvider({	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	},})

Declare editor:folding.

Workspace Tabs

Open vault files:

this.api.workspace.openFile("Projects/Plan.md", { target: "right", newTab: true })

Open a registered plugin view:

this.api.workspace.openView("dashboard", { target: "active" })

Open generated Markdown without writing a file:

this.openMarkdownTab({	title: "Plugin Report",	content: "# Report\n\nGenerated by my plugin.",})