Twig plugins

A plugin is an ES module Twig imports by URL. It can add slash commands, render macros inside blocks, open a panel in the sidebar, own a screen of its own, read and write the graph, and listen for changes.

Installing one

1. Open Plugins from Settings › More. Five ship with Twig and install with one press.
2. Anything else goes in as a URL, under From a URL at the bottom of that screen.
3. Twig imports the module and calls its default export, passing the API, and again each time the plugin is switched on.
4. Turning a plugin off undoes everything it registered; so does removing it.

The smallest plugin that does something

export const name = 'Shout'

export default function (twig) {
  twig.macros.add('shout', (args) => {
    const el = document.createElement('strong')
    el.textContent = args.toUpperCase()
    return el
  })
}

Type {{shout hello}} in any block and it renders HELLO. There is nothing to clean up: switching the plugin off takes the macro with it, and whatever the default export returns is called then too.

Types

The API is typed in src/plugins/types.ts: TwigApi, TwigPlugin, and the Page and Block records it hands back. There is no published twig package to import it from, so a plugin written in TypeScript copies that one file next to its own source; it imports nothing. A plugin shipped as plain JavaScript needs no build step at all.

// twig-types.ts is a copy of src/plugins/types.ts
import type { TwigApi, TwigPlugin } from './twig-types.ts'

const plugin: TwigPlugin = (twig: TwigApi) => { /* … */ }
export default plugin

Where plugins are kept