Manifest and Capabilities
Define plugin identity, bundle paths, and runtime permissions for reviewed extension behavior.
Every community plugin has a manifest.json at the plugin root. The plugin entry imports it and
passes it to definePlugin, so the loader and the bundle always agree on the id.
Manifest Shape#
{ "id": "example-plugin", "name": "Example Plugin", "version": "0.1.0", "minAppVersion": "0.1.0", "author": "Your Name", "authorUrl": "https://example.com", "description": "Adds a sample command and sidebar view.", "icon": "puzzle", "main": "dist/index.js", "permissions": ["vault:read", "workspace:tabs"]}import { definePlugin, type PluginManifest } from "@cortex.md/api"import manifest from "../manifest.json"export default definePlugin({ manifest: manifest as PluginManifest,})| Field | Required | Notes |
|---|---|---|
id | Yes | Stable id unique inside a vault. Must match the bundle and the Marketplace entry. |
name | Yes | User-facing name; also labels the plugin settings page. |
version | Yes | Plain MAJOR.MINOR.PATCH. Pre-release suffixes break update checks. |
minAppVersion | Yes | Minimum Cortex version the plugin expects. |
author | Yes | Displayed in plugin and Marketplace surfaces. |
authorUrl | No | Public URL for the author or organization. |
description | Yes | Short install/review summary. |
icon | Yes | Lucide icon name. |
main | Yes | Safe relative path to the bundle, usually dist/index.js. |
permissions | No | Runtime context APIs the plugin calls. Unknown values fail the load. |
When you release, the CLI mirrors permissions into a capabilities field of the release
manifest.json automatically. Do not maintain it by hand.
Contributions Need No Permission#
Commands, views, sidebar items, status bar items, context menu items, settings, Markdown rules,
property types, fold providers, and editor extensions are granted by declaring them under
contributes. The plugin's capabilities are derived from that declaration.
Runtime Permissions#
PLUGIN_PERMISSIONS lists every value. A context call without its permission throws (or, for
notifications, returns { delivered: false, reason: "missing-capability" }).
| Permission | Enables |
|---|---|
vault:read | ctx.vault reads, listings, exists, getVaultPath, and ctx.metadata. |
vault:write | ctx.vault.writeFile. |
vault:delete | ctx.vault.deleteFile. |
vault:watch | ctx.vault.onFileEvent. |
editor:read | Active file path and content. |
editor:write | insertAtCursor and replaceSelection. |
workspace:tabs | Opening files, plugin views, and temporary Markdown tabs; open-file reads. |
theme:read | Active theme name and theme change subscriptions. |
bookmarks:read | Bookmark list, lookup, and change subscriptions. |
bookmarks:write | Add, remove, and toggle bookmarks. |
data | Plugin-owned data files. |
notifications | Native notifications and ctx.ui.showNotice. |
Best Practices#
- Request the narrowest set of permissions you need; permissions are user-visible.
- Do not call APIs defensively and ignore permission failures. Declare the permission or remove the feature.
- Use local ids for plugin commands, views, settings, and context menu items. Cortex prefixes where global uniqueness is needed.