Common Ink
All docs

Plugins

Turn Common Ink's plugins on and off, install plugins from the plugin directory for the workspace or for yourself, decide what each may do, and publish, fork and change your own.

Most of Common Ink is plugins, such as the sidebar, tabs and splits, the command palette, and Vim mode. A third-party plugin is one someone published to the plugin directory, which an admin installed for the workspace or a member installed for themself.

Turn a plugin on or off

Open Plugins under More in the sidebar. Each plugin is a card with a switch, under a heading such as Writing, Embeds or Modes. Turn a plugin off and what it adds goes away until you turn it back on. The choice is yours alone, and it follows you to other browsers.

Most built-in plugins start on, and a few start off, such as Vim mode. Press a card to open the plugin's page, with what it adds, its permissions, its settings, and its source. A built-in plugin's page says under Permissions whether it runs inside the app with everything you have, or shut off from it, as Word count and Quick timer do.

The plugins installed in this workspace are last, and each card says what kind it is:

Label What it means
Third-party An admin installed it for the workspace, and it runs shut off from the app
Third-party, full trust An admin installed it, and it runs inside the app once it is granted and you turn it on
Just for you You installed it for yourself. Nobody else sees it, admins included

A third-party plugin is off for each member until that member turns it on.

Find and install a plugin

Browse on the Plugins page is the plugin directory: the plugins published in this workspace, the ones their publishers made public for everyone on Common Ink, and the ones that come with Common Ink. Search it by name, or narrow it with filters such as is:installed or capability:notes.read. Open a plugin to read what it asks for, with the reason its author gave, its versions, and its code under Source. Each version is named by its digest, and the app checks the code against it before it says a version is verified.

  • Install puts it in the workspace for everyone, and is an admin's. Installing allows nothing: each permission is off until an admin allows it.
  • Use it myself installs it for you alone, if you may publish plugins here. Nobody else sees it or decides for it, admins included, and it goes when you leave the workspace. It never runs with full trust.

When a newer version is published, the plugin's card says Update available, and its page offers the update. An update turns every permission off until it is allowed again for the new code. If the plugin adds embeds, its page warns you that an embed runs as soon as a note with one is opened, on whatever an editor of that note wrote. The menu on the plugin's page has Uninstall….

What a plugin can ask for

Permission What it allows
Read notes The notes and folders you can see, which of them link to a note, and search across them
Write notes Make notes and change the ones you can change. History records each change as the plugin's
Read todos The todos in the notes you can see
Read members' names The names and roles of the workspace's members, never their emails
Use the network Load from and send to the sites it lists, and no other
Full trust Run inside Common Ink, with everything you can do

A plugin acts as you and never has more than you do. If you are a viewer, a plugin allowed to write notes still can't change one.

An approval is for one version of the code, named by its SHA-256 hash. When an admin updates a plugin, every permission goes off until an admin allows it for the new code. A permission whose reason or sites change goes off too.

A plugin asks for a permission the first time it needs one, just after you use it. For a plugin installed for the workspace, an admin's answer is for everyone, and a member who isn't an admin sees Ask an admin in place of Allow: nothing is allowed until an admin approves. For one you installed for yourself, the answer is yours alone, and you can change it on its page.

Full trust

A plugin with full trust runs inside Common Ink instead of shut off from it. It runs for you only while both of these hold:

  • An admin granted this exact code, with Allow on its Full trust permission.
  • You turned it on for yourself with the switch on its page, and confirmed the warning with Turn it on for me.

Nobody can turn it on for you, an admin included. Any change to its code ends it for everyone, until an admin grants the new code and each member turns it on again.

While you have it on, it can do anything you can do, in every workspace you belong to. It can read and change every note you can open, your private notes included, see what you type, and send any of it anywhere. It can create an agent token in your name and share your notes by link, and both keep working after you turn it off. If you are an admin, it can also invite people, change roles, and approve plugins, a new version of itself included. It can't see notes you can't see.

Turning it off loads Common Ink again, so none of its code is left running. Code that means harm can get in the way of that in a window it already runs in, and closing that window ends it.

What the sandbox doesn't cover

A plugin without full trust runs in a frame shut off from the app. A few things still get through:

  • WebRTC. A frame can open a WebRTC connection, and no browser lets Common Ink block it. So a plugin can send what it is allowed to read to another computer, with or without the network permission. Allow Read notes only for a plugin you would trust to send those notes out.
  • Names. Everything a plugin shows starts with its name and the word "plugin". It can't take one of Common Ink's own names, but it can pick a misleading name of its own.
  • Who changed a note. A plugin that reads notes sees who last changed each one, by name.

Publish a plugin

Publish a plugin, on the Plugins page, takes a plugin's two files, manifest.json and its code: drop them, choose them, or paste them. Nothing is fetched from anywhere, so what you publish is what runs. Choose who sees it:

  • Only me: you alone, to use for yourself. Nobody else is told of it, admins included.
  • This workspace: the members of this workspace, where an admin can install it.
  • Everyone on Common Ink: every workspace, whose admins can install it. Your name is shown as its publisher.

A workspace's admin can keep publishing to admins in Settings, under Plugin directory. An agent can publish for you with publish_plugin; what it publishes is Only me unless you asked for more.

Change a plugin

A plugin's page only reads. To change one, press Fork… on it: that publishes a copy of your own, which says what it was forked from. To change a plugin you published, open it and press Changes.

Changes are written outside the app, by your agent or in your own editor, and saved as unpublished changes: yours alone, admins included. Ask your agent, for instance: "Change my Word count plugin in Common Ink so that it says minutes to read." Or save the files yourself with ink plugin-changes-save. The Changes page shows what changed in each file against the latest version, and updates within a few seconds of each save.

  • Try it runs your changes in place of your own install of the plugin, for you alone, with what you allowed that install and never more. It stays on while your agent saves again, so you can watch each change run. Only you can turn it on.
  • Publish as version N… publishes them, and asks who sees the plugin.
  • Discard changes… throws them away.

When something goes wrong

Your agent can't see a plugin run: your browser does. So while you run a plugin you installed for yourself, or try your changes, your app keeps what its code threw and didn't catch, with the line it was on, and each call it made that the app refused. Your agent reads them with the plugin, and the plugin's page or the Changes page lists them under "What went wrong". New code starts with none.

Build a plugin

Ask your agent to write one: it gets a new plugin's files with everything a plugin can call. Or start one yourself. ink plugin-new writes a manifest and code to start from, with the plugin API beside them. ink plugin-validate says what installing them would make of them, or why it would be refused. Neither installs anything. The ink command shows how to set up ink.

ink plugin-new "Reading time" --out reading-time
ink plugin-validate --manifest @reading-time/manifest.json --code @reading-time/plugin.js

Plugin API has the manifest, the ink object a plugin's code is handed, every operation it may perform, and styling.