@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.
- package/dist/theme-app.css +2 -5
- package/dist/types/shared/plugin/api.d.ts +16 -0
- package/dist/types/shared/plugin/components.d.ts +109 -0
- package/dist/types/shared/plugin/contributions.d.ts +3 -2
- package/dist/types/shared/plugin/messages.d.ts +22 -0
- package/dist/types/ui.d.ts +26 -9
- package/dist/vite.js +75 -10
- package/docs/README.md +24 -0
- package/docs/config.md +132 -0
- package/docs/context.md +417 -0
- package/docs/package.md +116 -0
- package/docs/publishing.md +71 -0
- package/docs/session.md +205 -0
- package/docs/start.md +173 -0
- package/docs/trust.md +51 -0
- package/docs/ui.md +145 -0
- package/docs/versions.md +33 -0
- package/package.json +3 -2
package/docs/context.md
ADDED
|
@@ -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)).
|
package/docs/package.md
ADDED
|
@@ -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.
|