@type32/vertex-plugin 1.0.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,417 @@
1
+ # The plugin's context
2
+
3
+ `main.js` default-exports `definePlugin({setup})`. Vertex calls `setup(ctx)` once in each window the plugin runs in
4
+ (`plugin.json`'s `windows`), with `ctx: PluginContext`.
5
+
6
+ ```ts
7
+ import {definePlugin} from '@type32/vertex-plugin'
8
+
9
+ interface Config {
10
+ depth: number
11
+ }
12
+
13
+ export default definePlugin<Config>({
14
+ setup(ctx) {
15
+ ctx.commands.register({id: 'hello', label: 'plugins.hello.command', run: () => console.log(ctx.config.value.depth)})
16
+ },
17
+ })
18
+ ```
19
+
20
+ - **`setup` is synchronous.** What it registers belongs to the plugin and is removed when the plugin stops; an `await`
21
+ would leave that. Do async work inside what it registers (a command's `run`, `onSession`). A `setup` that throws, or
22
+ returns a promise, fails the plugin: it's stopped and the user is told "{name} couldn't start".
23
+ - **Every registration returns what removes it.** Rarely needed: everything goes when the plugin stops, and what's
24
+ registered in an `onSession` callback goes with the session.
25
+ - **Ids are global.** Panel views and tab kinds are saved in layouts and sessions by id, so start yours with the
26
+ plugin's id (`hello`, `hello-stats`). A command's id is the plugin's own (`<plugin id>:<id>`).
27
+ - **Labels are i18n keys** of the plugin's (`plugins.hello.view`) unless the type says "already translated"
28
+ ([strings](package.md#strings)).
29
+ - **UI** is a `component` (a lazily loaded Vue component that gets the props) or a `mount(el, props)` that draws into
30
+ `el` and returns what undoes it ([UI](ui.md)). Either draws inside an error boundary that names the plugin.
31
+ - `definePlugin<Config>` types [`ctx.config`](config.md#ctxconfig).
32
+
33
+ ## About the plugin and the window
34
+
35
+ ### `ctx.plugin.id`, `ctx.plugin.version`, `ctx.plugin.source`, `ctx.plugin.assetUrl`
36
+
37
+ Its id and version as its manifest says, and `source`: `global` (installed for every workspace), `workspace` (a
38
+ workspace's own) or `core`. `assetUrl(path)` is a URL for a file of the plugin's folder (`logo.svg`, `data/words.json`,
39
+ nothing outside it), for an `<img>`, `fetch` or `import()`; the build puts `public/` at the folder's top.
40
+
41
+ ### `ctx.window.kind`, `ctx.window.label`
42
+
43
+ The window it runs in: `main` (the start page), `session` (a workspace or a single file), `settings`; and the window's
44
+ label, unique among the open windows.
45
+
46
+ ### `ctx.i18n.t`, `ctx.i18n.locale`
47
+
48
+ `t(key, params?)` is a string in the window's language (`t('plugins.hello.count', {n: 3})`), the key itself when
49
+ there's none; `locale` is the language (`en`, `zh-CN`). Both are reactive: a template or a `computed` that reads them
50
+ follows a change of language.
51
+
52
+ ### `ctx.ui.theme.dark`, `ctx.ui.theme.value`
53
+
54
+ The window's theme, for what CSS can't reach (a `<canvas>`, a chart library). `dark` is whether it's dark; `value(name)`
55
+ reads a CSS custom property as the page resolves it now (`value('--ui-primary')`, `value('--ui-text-muted')`). Both
56
+ are reactive: a `watchEffect` that reads them runs again when the user changes light and dark, the colours, or a
57
+ workspace's theme. CSS and Tailwind classes follow the theme by themselves ([styles](ui.md#styles)).
58
+
59
+ ## Commands
60
+
61
+ ### `ctx.commands.register`
62
+
63
+ ```ts
64
+ ctx.commands.register({
65
+ id: 'open-graph',
66
+ label: 'plugins.hello.openGraph',
67
+ icon: 'i-lucide-waypoints',
68
+ accelerator: 'CmdOrCtrl+Shift+G',
69
+ menu: {section: 'view'},
70
+ palette: true,
71
+ enabled: () => true,
72
+ run: () => {},
73
+ })
74
+ ```
75
+
76
+ Registered as `<plugin id>:<id>`. `menu` puts it in the menu bar's section (`app`, `file`, `edit`, `view`, `help`),
77
+ after Vertex's items; `group` (default 100: the end) places it among Vertex's groups. `accelerator` is the menu item's
78
+ shortcut, so it works while the item is in the menu. `palette` lists it in the command palette's Commands. `enabled`
79
+ is asked whenever the menu or the palette is drawn.
80
+
81
+ ### `ctx.commands.paletteGroup`
82
+
83
+ A group of items in the command palette, computed when the palette opens: the open base's commands, each workflow.
84
+
85
+ ```ts
86
+ ctx.commands.paletteGroup({
87
+ id: 'hello-recent',
88
+ label: () => ctx.i18n.t('plugins.hello.recent'),
89
+ items: () => [{id: 'a', label: 'A note', icon: 'i-lucide-file', onSelect: () => {}}],
90
+ order: 40,
91
+ })
92
+ ```
93
+
94
+ `label()` and the items' labels are already translated. Groups sort by `order`: Vertex's Quick actions are 0,
95
+ Commands 10, Files 100; default 50.
96
+
97
+ ## Views
98
+
99
+ ### `ctx.views.panel`
100
+
101
+ A view in a sidebar or the bottom panel.
102
+
103
+ ```ts
104
+ ctx.views.panel({
105
+ id: 'hello',
106
+ label: 'plugins.hello.view',
107
+ icon: 'i-lucide-hand',
108
+ defaultArea: 'right',
109
+ tab: true,
110
+ component: () => import('./View.vue'),
111
+ })
112
+ ```
113
+
114
+ The component gets `PanelViewProps`: `session` (the window's [session](session.md)), `placement` (`panel`, or `tab`
115
+ when it's open in a tab) and `actions(list)`, which sets the buttons in the panel's header (refresh, collapse all):
116
+
117
+ ```ts
118
+ props.actions([{id: 'refresh', label: ctx.i18n.t('plugins.hello.refresh'), icon: 'i-lucide-refresh-cw', onSelect: () => {}}])
119
+ ```
120
+
121
+ - `defaultArea`: where it first goes (`left`, `right`, `bottom`, `hidden`) while the user's layout doesn't place it.
122
+ The user moves it from there.
123
+ - `tab: true`: it may also open in a tab ([`session.views.openInTab`](session.md#sessionviewsshow-sessionviewsopenintab)),
124
+ so it must work mounted twice at once.
125
+ - `when(context)`: whether it can show in this window (`context.isWorkspace`, `context.activeFile`, `context.settings`).
126
+ - `scroll: true` wraps it in the panel's fading scroll area, for a view that doesn't scroll by itself.
127
+ - `search(context)`: what the panel's Search button does while it's shown; `kbds(context)`: a shortcut hint.
128
+ - `action(context)` instead of a component: the view is a button that runs it (Search is one).
129
+
130
+ ### `ctx.views.tabKind`
131
+
132
+ A kind of tab that isn't a file's (a chat, a diff). Its tabs are opened with
133
+ [`session.tabs.open(id, kind)`](session.md#sessiontabsopen-sessiontabsclose-sessiontabsactive-sessiontabslist).
134
+
135
+ ```ts
136
+ ctx.views.tabKind({
137
+ kind: 'hello-report',
138
+ describe: id => ({label: ctx.i18n.t('plugins.hello.report', {id}), icon: 'i-lucide-file-chart-column'}),
139
+ persist: true,
140
+ exists: id => id !== '',
141
+ component: () => import('./Report.vue'),
142
+ })
143
+ ```
144
+
145
+ The component gets `TabProps`: `session` and `id`, the tab's id within the kind. `describe(id)` names the tab in the
146
+ tab bar (already translated), `undefined` when what it shows is gone. `persist` reopens it after a relaunch, once
147
+ `exists(id)` says it still has something to show.
148
+
149
+ ### `ctx.views.fileViewer`
150
+
151
+ What a tab of a file draws, for the extensions it matches.
152
+
153
+ ```ts
154
+ ctx.views.fileViewer({
155
+ id: 'board',
156
+ match: ext => ext === 'board',
157
+ loadsText: true,
158
+ component: () => import('./BoardViewer.vue'),
159
+ })
160
+ ```
161
+
162
+ The component gets `ViewerProps`. With `loadsText`, the tab reads the file as UTF-8 into `modelValue`, and a
163
+ `v-model` update autosaves it (undo, the unsaved dot and reloads on an outside change are the tab's). Without it, the
164
+ viewer reads the file itself, from `assetUrl` or through the session. `fileName` (`v-model:fileName`) is the editable
165
+ title; draw the header, title and status bar with `ViewerLayout` ([UI](ui.md#vertexs-components)), passing its
166
+ `on-rename` to `onRename`. `modes` limits it to `workspace` or `singlespace` windows; the highest `priority` wins when
167
+ several viewers match (default 0; Vertex's code editor, the fallback, is -100).
168
+
169
+ ### `ctx.views.statusItem`
170
+
171
+ Something a viewer shows besides its content: in its status bar (a counter), or over its right edge (`placement:
172
+ 'side'`).
173
+
174
+ ```ts
175
+ ctx.views.statusItem({
176
+ id: 'hello-chars',
177
+ viewers: ['markdown'],
178
+ mount(el, props) {
179
+ el.textContent = `${props.text.length}`
180
+ return () => el.replaceChildren()
181
+ },
182
+ })
183
+ ```
184
+
185
+ It gets `StatusItemProps`: the shown file's `text`, `filePath`, `fileId` and `session`. `viewers` lists the viewers it
186
+ shows for (Vertex's note editor is `markdown`); default every viewer that loads text.
187
+
188
+ ### `ctx.views.overlay`
189
+
190
+ UI drawn once in each session window, over everything (the command palette is one). It gets `{session}`; `when`
191
+ limits it to some windows.
192
+
193
+ ## Files
194
+
195
+ ### `ctx.files.type`
196
+
197
+ A kind of file: its icon in Files, and with `new`, a New item in File → New, Files' menus and the palette.
198
+
199
+ ```ts
200
+ ctx.files.type({
201
+ id: 'board',
202
+ extensions: ['board'],
203
+ icon: 'i-lucide-square-kanban',
204
+ label: 'plugins.board.fileType',
205
+ new: {label: 'plugins.board.new', command: 'plugins.board.newCommand', description: 'plugins.board.newDescription'},
206
+ })
207
+ ```
208
+
209
+ New asks for a name and makes an empty file, so the file's viewer reads empty text as a new one. Pair it with a
210
+ [viewer](#ctxviewsfileviewer) and, when the format holds links, a [link extractor](#ctxindexlinkextractor).
211
+
212
+ ### `ctx.files.menuItem`
213
+
214
+ A group of items in the right-click menu of a file or a selection, at the top.
215
+
216
+ ```ts
217
+ ctx.files.menuItem({
218
+ id: 'hello-count',
219
+ items: ({files}) => [{label: ctx.i18n.t('plugins.hello.count', {n: files.length}), icon: 'i-lucide-hash', onSelect: () => {}}],
220
+ })
221
+ ```
222
+
223
+ ## Settings and the start page
224
+
225
+ ### `ctx.settings.page`
226
+
227
+ A page of the Settings window, at `/settings/<id>`, in the nav under the plugin. The plugin must run in the Settings
228
+ window (`"windows": ["session", "settings"]`). A plugin with only a schema doesn't need one: Settings draws it from
229
+ the manifest ([Config](config.md#the-schema)).
230
+
231
+ ```ts
232
+ ctx.settings.page({
233
+ id: 'hello',
234
+ label: 'plugins.hello.settings',
235
+ component: () => import('./SettingsPage.vue'),
236
+ })
237
+ ```
238
+
239
+ The component gets `SettingsPageProps`: `path` (the route below the page: `/settings/hello/a/b` → `['a', 'b']`) and
240
+ `config` (`ScopedConfig`: the plugin's config in the scope Settings is editing, the user's or a workspace's). Draw it
241
+ with `SettingsScrollLayout`, `SettingsSection` and `SettingsRow` ([UI](ui.md#vertexs-components)) so it looks and
242
+ behaves like Vertex's pages. `children` adds sub-entries to the nav (`{label, icon, path}`); `icon` defaults to the
243
+ manifest's.
244
+
245
+ ### `ctx.settings.open`
246
+
247
+ Opens the Settings window (or brings it forward) at `/settings/<path>`, on the calling window's scope.
248
+
249
+ ### `ctx.home.action`
250
+
251
+ A button on the start page, after New Workspace (Clone Workspace… is one). The plugin must run in the main window
252
+ (`"windows": ["main"]`). `run(home)` gets `home.openWorkspace(path)`.
253
+
254
+ ## The editor
255
+
256
+ What's added to the note editor, Vertex's Markdown editor (CodeMirror 6, `@type32/codemirror-rich-obsidian-editor`).
257
+
258
+ ### `ctx.editor.extension`
259
+
260
+ A CodeMirror extension, in every note editor. `{nested: true}` puts it also in the editors inside callouts, table
261
+ cells and canvas cards.
262
+
263
+ ```ts
264
+ import {EditorView} from '@codemirror/view'
265
+
266
+ const theme = EditorView.theme({'.cm-line': {letterSpacing: '0.01em'}})
267
+ ctx.editor.extension(theme, {nested: true})
268
+ ```
269
+
270
+ A function `(host) => extension` gets each editor's `EditorHost` (`session`, `notePath`). What it returns must be the
271
+ same objects on every call (module constants; options through a facet), or CodeMirror remounts them.
272
+
273
+ ### `ctx.editor.codeBlock`
274
+
275
+ A fenced code block drawn as a widget, in notes, callouts, table cells and canvas cards.
276
+
277
+ ````ts
278
+ ctx.editor.codeBlock({
279
+ language: 'statblock',
280
+ mount(el, {codeContent, host}) {
281
+ el.textContent = `${host.notePath}: ${codeContent.length} characters`
282
+ return () => el.replaceChildren()
283
+ },
284
+ })
285
+ ````
286
+
287
+ It gets `codeContent` (the fence's text) and `host`.
288
+
289
+ ### `ctx.editor.embed`
290
+
291
+ How `![[file]]` draws the files it matches, in notes and canvas cards.
292
+
293
+ ```ts
294
+ ctx.editor.embed({
295
+ id: 'board',
296
+ match: ext => ext === 'board',
297
+ linkName: 'name',
298
+ component: () => import('./BoardEmbed.vue'),
299
+ })
300
+ ```
301
+
302
+ It gets `EmbedProps`: `filePath` (workspace-relative), `subpath` (after `#`), `display` (after `|`), `assetUrl`,
303
+ `host`, and `card: true` in a canvas card, where it fills the box.
304
+
305
+ ### `ctx.editor.markdown`
306
+
307
+ Syntax the editor's parser reads, in notes and everything nested in them: a Lezer `MarkdownConfig`
308
+ (`@lezer/markdown`).
309
+
310
+ ```ts
311
+ import type {MarkdownConfig} from '@lezer/markdown'
312
+
313
+ const roll: MarkdownConfig = {
314
+ defineNodes: [{name: 'DiceRoll'}],
315
+ parseInline: [{
316
+ name: 'DiceRoll',
317
+ parse(cx, next, pos) {
318
+ if (next !== 123 /* { */) return -1
319
+ const end = /^\{\d*d\d+(?:[+-]\d+)?\}/.exec(cx.slice(pos, cx.end))?.[0].length
320
+ return end ? cx.addElement(cx.elt('DiceRoll', pos, pos + end)) : -1
321
+ },
322
+ }],
323
+ }
324
+ ctx.editor.markdown(roll)
325
+ ```
326
+
327
+ Parsing gives the syntax a node; drawing it (a decoration, a widget) is an [extension](#ctxeditorextension)'s job,
328
+ which finds the nodes with `syntaxTree(state)` (`@codemirror/language`).
329
+
330
+ ### `ctx.editor.slashItem`, `ctx.editor.toolbarItem`
331
+
332
+ An item in the slash menu (`/` in a note), or in the toolbar over a selection: the editor's `EditorAction`.
333
+
334
+ ```ts
335
+ ctx.editor.slashItem({
336
+ id: 'hello-statblock',
337
+ label: 'plugins.hello.statblock',
338
+ icon: 'i-lucide-swords',
339
+ keywords: ['creature', 'monster'],
340
+ run: view => {
341
+ const at = view.state.selection.main.head
342
+ view.dispatch({changes: {from: at, insert: '```statblock\nname: Goblin\n```\n'}})
343
+ },
344
+ })
345
+ ```
346
+
347
+ ### `ctx.editor.noteMenuItem`
348
+
349
+ A group of items in a note's right-click menu, after Cut, Copy, Paste and Select all. `items({host, selection})` gets
350
+ the selected text; an item's `onSelect` runs once the menu has closed.
351
+
352
+ ## The index
353
+
354
+ ### `ctx.index.linkExtractor`
355
+
356
+ The links in a file format that isn't Markdown, so its files count in backlinks and the graph, and renames update
357
+ them.
358
+
359
+ ```ts
360
+ import {getInternalLinks, rewriteLinks} from '@type32/vertex-plugin/links'
361
+
362
+ ctx.index.linkExtractor({
363
+ id: 'board',
364
+ match: ext => ext === 'board',
365
+ targets: text => getInternalLinks(text).map(link => link.path),
366
+ rewrite: (text, rename) => rewriteLinks(text, rename),
367
+ })
368
+ ```
369
+
370
+ `targets(text)` returns the link targets as written (`target` of `[[target]]`). `rewrite(text, rename)` returns the
371
+ text with each renamed target replaced (`rename`: old target → new) and how many changed; without it, links in these
372
+ files aren't updated on a rename. For a format that holds Markdown inside JSON, read and rewrite the Markdown parts.
373
+
374
+ ## Sessions
375
+
376
+ ### `ctx.onSession`
377
+
378
+ ```ts
379
+ ctx.onSession(session => {
380
+ session.index.on(event => console.log(event.type))
381
+ })
382
+ ```
383
+
384
+ Runs in a session window once its workspace's index is built (at once, if it already is), with the
385
+ [session](session.md). What it registers and listens to ends with the session. Views, viewers and the rest get the
386
+ session as a prop; `onSession` is for work that isn't drawn (an index listener, a palette group of the workspace's).
387
+
388
+ ## Other plugins
389
+
390
+ ### `ctx.provide`, `ctx.use`, `ctx.whenPlugin`
391
+
392
+ `provide(api)` offers an object to other plugins. `use(id)` is a running plugin's API, `undefined` when it isn't
393
+ running in this window; `whenPlugin(id, fn)` runs `fn` with it now or once that plugin starts.
394
+
395
+ ```ts
396
+ ctx.whenPlugin('bases', bases => {
397
+ bases.registerView({type: 'calendar', label: 'plugins.hello.calendar', icon: 'i-lucide-calendar', component: () => import('./Calendar.vue')})
398
+ })
399
+ ```
400
+
401
+ Put the plugin you use in `requires` (`"requires": ["bases"]`, or `"bases?"` when it's optional). The SDK types the
402
+ APIs of Vertex's own plugins: `bases` (`registerView`, `Value`), `ai`, `chat`, `mermaid` (`Diagram`), `workflows`
403
+ (`run`, `dryRun`, `registerNodes`). A community plugin's API can be provided and used at run time, but it can't be
404
+ typed yet.
405
+
406
+ ## Dialogs
407
+
408
+ ### `ctx.dialogs.open`, `ctx.dialogs.save`
409
+
410
+ The system's Open and Save dialogs: an absolute path, `null` when cancelled. What's picked is this window's to read
411
+ (open) or write (save), even outside the workspace.
412
+
413
+ ```ts
414
+ const path = await ctx.dialogs.open({title: 'Import', filters: [{name: 'CSV', extensions: ['csv']}]})
415
+ ```
416
+
417
+ `directory: true` picks a folder. Files inside the workspace are the session's ([session](session.md#files)).
@@ -0,0 +1,116 @@
1
+ # The package
2
+
3
+ ## What Vertex installs
4
+
5
+ A folder named by the plugin's id:
6
+
7
+ | File | |
8
+ | --- | --- |
9
+ | `plugin.json` | The manifest. |
10
+ | `main.js` | One ES module with no imports; its default export is `definePlugin({setup})`. |
11
+ | `styles.css` | Optional. Put in the page when the plugin loads, before its code runs. |
12
+ | `locales/<locale>.json` | Optional. The plugin's strings. |
13
+ | anything else | Assets, read through [`ctx.plugin.assetUrl`](context.md#ctxpluginid-ctxpluginversion-ctxpluginsource-ctxpluginasseturl). |
14
+
15
+ Vertex keeps it in its data folder (`plugins/<id>/`), or in a workspace's `.vertex/plugins/<id>/` for a workspace's
16
+ own ([Trust](trust.md#a-workspaces-plugins)), with `.install.json` beside, its record of where it came from.
17
+
18
+ ## `plugin.json`
19
+
20
+ Unknown keys are errors; the build lists every problem.
21
+
22
+ | Key | |
23
+ | --- | --- |
24
+ | `id` | Lowercase letters, digits and inner hyphens, at most 50 characters. The installed folder's name. It names the plugin's strings (`plugins.<id>`), settings (`plugins.config.<id>`), data and secrets, so it's for good. It can't be a core plugin's (`files`, `canvas`, `bases`, `git`, `chat`, `ai`…). |
25
+ | `name` | Shown in Settings and in messages ("Hello couldn't start"). Not translated. |
26
+ | `version` | Shown, compared for updates, and what a release's tag should be (`0.2.0` or `v0.2.0`). |
27
+ | `description` | Optional, one sentence, shown in Settings and the install dialog. |
28
+ | `icon` | Optional. An Iconify name (`i-lucide-hand`) for the plugin's rows and settings page. |
29
+ | `author` | Optional, shown. |
30
+ | `repository` | Optional. Its Git repository, `https://…`: where it says it lives. Vertex shows it, and records where it actually fetched the plugin from, which it uses for updates ([Publishing](publishing.md)). |
31
+ | `apiVersion` | `1`. Vertex refuses a plugin that asks for a newer one ([Versions](versions.md)). |
32
+ | `minAppVersion` | Optional. The oldest Vertex it runs in (`0.9.2`); an older one keeps it off. |
33
+ | `windows` | Optional. The kinds of window it runs in: `session` (a workspace or a file), `main` (the start page), `settings`. Default `["session"]`. A plugin with a settings page of its own runs in `settings` too. |
34
+ | `requires` | Optional. Plugin ids it needs (`["bases"]`); a trailing `?` marks one it uses when it's there (`"chat?"`). Without a required one, it's off and Settings says why. |
35
+ | `permissions` | Optional. `network`, `secrets`, `files-outside-workspace` ([what each grants](config.md#permissions)). |
36
+ | `enabledByDefault` | Optional. Ignored for a plugin someone installs, which the install turns on. |
37
+ | `config` | Optional. Its settings: `schema` (drawn by Settings), `overridable` (what a workspace may change) ([Config](config.md)). |
38
+
39
+ ## The build
40
+
41
+ `vertex(options)` from `@type32/vertex-plugin/vite`, in `vite.config.ts`:
42
+
43
+ - builds `options.entry` (default `src/main.ts`) as one `main.js`: everything it imports is bundled, dynamic imports
44
+ included (`main.js` is loaded from memory, where a second file can't be found), and `process.env.NODE_ENV` is
45
+ `production`;
46
+ - reads [the modules Vertex shares](#what-the-plugin-shares-with-vertex) from Vertex's own copies;
47
+ - runs Tailwind, and writes the plugin's CSS as `styles.css`;
48
+ - checks `plugin.json` and `locales/*.json` and copies them;
49
+ - copies `public/` (Vite's own rule) to the top of `dist/`;
50
+ - with `pack: true`, writes `plugin.zip` beside `dist/`, the asset a release carries ([Publishing](publishing.md)).
51
+ - with `vite build --watch`, builds again on each change of the source, never of its own output.
52
+
53
+ Add `@vitejs/plugin-vue` before it to write `.vue` files.
54
+
55
+ ## What the plugin shares with Vertex
56
+
57
+ Some imports aren't bundled: the build turns them into Vertex's own copies, so there's one Vue, one editor and one
58
+ Nuxt UI in a window, and a plugin's `ref` or toast is the app's:
59
+
60
+ - `vue`;
61
+ - `@codemirror/autocomplete`, `commands`, `lang-markdown`, `language`, `language-data`, `lint`, `search`, `state`,
62
+ `view`, and `@lezer/common`, `highlight`, `markdown`;
63
+ - `@type32/codemirror-rich-obsidian-editor`, `/kit`, `/ext` (Vertex's editor);
64
+ - `@nuxt/ui/composables` (`useToast`, `useOverlay`…). Nuxt UI's components aren't imported: they're there by name.
65
+ Any other import from `@nuxt/ui` fails the build;
66
+ - this package: `@type32/vertex-plugin` (`definePlugin`), `/ui` ([Vertex's components](ui.md#vertexs-components)),
67
+ `/vault`, `/links`, `/files`, `/text` (the helpers below).
68
+
69
+ Importing a name Vertex's copy doesn't export fails the build. These are the versions this package depends on; a new
70
+ major of one is a new `apiVersion`.
71
+
72
+ The helpers are Vertex's own, the ones its features use:
73
+
74
+ | Module | |
75
+ | --- | --- |
76
+ | `@type32/vertex-plugin/vault` | `Vault` (what [`session.files.vault`](session.md#sessionfilesvault) returns), path helpers, tags, patterns, frontmatter written as Obsidian writes it (`setFrontmatterProperty`). |
77
+ | `@type32/vertex-plugin/links` | Wiki links in Markdown text: `getInternalLinks`, `rewriteLinks`, `renameTargets` (for a [link extractor](context.md#ctxindexlinkextractor)). |
78
+ | `@type32/vertex-plugin/files` | File names and kinds: `fileNameFromPath`, `getFileExtensionFromPath`, `isImage`, `isPlainTextFile`, `IMAGE_TYPES`. |
79
+ | `@type32/vertex-plugin/text` | Line diffs: `lineDiff`, `diffCounts` (what `TextDiff` draws). |
80
+
81
+ ## Dependencies
82
+
83
+ Any other package is bundled into `main.js`: install it and import it (`d3-force`, `yaml`). Keep an eye on the size:
84
+ `main.js` is read whole when a window starts the plugin. A part used rarely can be a file in `public/`, loaded with
85
+ `import(ctx.plugin.assetUrl('part.js'))` when it's needed; it must be built as a module of its own, with no imports.
86
+
87
+ A dependency that imports `@vue/reactivity` or `@vue/runtime-core` itself (not `vue`) gets its own copy of them,
88
+ which doesn't react with Vertex's.
89
+
90
+ ## Strings
91
+
92
+ A plugin's strings are files, `locales/<locale>.json`, so Settings can show its labels without running it:
93
+
94
+ ```json
95
+ {"plugins": {"hello": {"view": "Hello", "count": "{n} notes"}}}
96
+ ```
97
+
98
+ - Everything is under `plugins.<id>`; Vertex reads nothing else from the file.
99
+ - `en.json` is required once there are strings. Any other locale has exactly its keys, each with the same `{params}`.
100
+ A language the plugin has no file for shows English.
101
+ - Every i18n key `plugin.json` names (its schema's labels, descriptions and options' labels) must be in `en.json`.
102
+ - The build checks all of it.
103
+
104
+ Where the contract says "i18n key" (a view's `label`, a command's, a file type's), give a key of the plugin's,
105
+ `plugins.<id>.…`, not text: Vertex translates it where it draws it, in the window's language, and follows a change of
106
+ language. Where it says "already translated" (a header button's label, a tab's `describe`), give text, from
107
+ [`ctx.i18n.t`](context.md#ctxi18nt-ctxi18nlocale). Vertex's languages are `en` and `zh-CN`.
108
+
109
+ ## What can't be done
110
+
111
+ - **Native code.** A plugin is JavaScript in Vertex's webview. What it can reach of the computer is what the contract
112
+ offers (files through the session, the network through `ctx.http`, the keychain through `ctx.secrets`).
113
+ - **Imports at run time**, besides its own files through `ctx.plugin.assetUrl`: `main.js` has none.
114
+ - **A sandbox.** A plugin runs as Vertex does; users are told so ([Trust](trust.md)).
115
+ - **Another community plugin's typed API.** `ctx.provide` works for any plugin, but `ctx.use` is typed for Vertex's own
116
+ plugins' APIs only ([`ctx.use`](context.md#ctxprovide-ctxuse-ctxwhenplugin)).
@@ -0,0 +1,71 @@
1
+ # Publishing
2
+
3
+ A plugin is published from a public Git repository on GitHub, GitLab, Gitea or Forgejo (self-hosted ones included).
4
+ Users install it with the repository's link (Settings → Plugins → Install…), and Vertex finds its updates there. It
5
+ needs no account and no forge API: it reads the repository's refs over HTTPS, as `git ls-remote` does.
6
+
7
+ Set `repository` in `plugin.json` to the repository's URL: Vertex shows it, and offers Use its repository to someone who
8
+ installed the plugin from elsewhere.
9
+
10
+ ## A release with `plugin.zip` (recommended)
11
+
12
+ A release whose tag is a version (`0.2.0` or `v0.2.0`, without a pre-release suffix) with an asset named `plugin.zip`:
13
+ the built plugin, its files at the top. `vertex({pack: true})` writes it beside `dist/`.
14
+
15
+ A workflow that releases on a tag, `.github/workflows/release.yml`:
16
+
17
+ ```yaml
18
+ name: Release
19
+
20
+ on:
21
+ push:
22
+ tags: ['v*']
23
+
24
+ permissions:
25
+ contents: write
26
+
27
+ jobs:
28
+ release:
29
+ runs-on: ubuntu-latest
30
+ steps:
31
+ - uses: actions/checkout@v5
32
+ - uses: oven-sh/setup-bun@v2
33
+ - run: bun install --frozen-lockfile
34
+ - run: bun run typecheck
35
+ - run: bun run build
36
+ - run: gh release create "$GITHUB_REF_NAME" plugin.zip --title "$GITHUB_REF_NAME" --generate-notes
37
+ env:
38
+ GH_TOKEN: ${{ github.token }}
39
+ ```
40
+
41
+ Then a release is: bump `version` in `plugin.json`, commit, `git tag v0.2.0`, `git push --tags`. Commit `bun.lock`.
42
+
43
+ Vertex picks the newest version tag whose release has a `plugin.zip` (the three newest are tried). On GitLab, the
44
+ asset is a release link whose direct path is `/plugin.zip`.
45
+
46
+ ## A branch of built files
47
+
48
+ A branch that holds the built plugin (`plugin.json` and `main.js` together) at its top or in `dist/`, followed as it
49
+ moves. A workflow can push `dist/` to a `dist` branch on each push to the main branch. A branch that holds only the
50
+ source is refused, with what to install instead.
51
+
52
+ ## What users can install
53
+
54
+ | They give | Vertex installs | Updates |
55
+ | --- | --- | --- |
56
+ | The repository's link | The newest release with `plugin.zip` | A newer release |
57
+ | A link to a branch (`…/tree/dist`) | That branch's files | A new commit |
58
+ | A link to a tag, or a commit | Those files | None: pinned |
59
+ | A `.zip` URL | The `.zip` | Other bytes at the URL |
60
+ | A `.zip` file or a folder | It | None (a folder is watched while developing) |
61
+
62
+ Users choose among the repository's latest release, its branches and its tags in the install dialog.
63
+
64
+ ## Updates
65
+
66
+ Vertex asks a plugin's source whether there's something newer when the user checks (Settings → Plugins → Check for
67
+ updates), and daily if they turned that on. A check sends one request per repository, carrying nothing about the user.
68
+ An update installs only when the user accepts it, through the same dialog, which shows what changed.
69
+
70
+ A workspace's copy of a plugin is pinned ([Trust](trust.md#a-workspaces-plugins)): an update installed from Settings is
71
+ pinned with it, and a copy changed any other way is off until the user accepts it again.