Skip to content

Plugins ​

A plugin is a program compiled to WebAssembly. It can provide modules, respond to events on the site, and show content on profiles. Plugins run in a sandbox and can use only the permissions they declare.

Plugins are still in beta. To request more functions for plugins to call, or to report other problems, contact WikitTeam directly.

Installing a plugin ​

Put the plugin in a folder named after it under plugins/ in the data directory:

text
plugins/
  scpper/
    plugin.json
    plugin.wasm
    config.json

If the plugin needs settings, create config.json in the same folder:

json
{
  "config": { "scpper_url": "http://127.0.0.1:8100" },
  "allowed_hosts": ["127.0.0.1"]
}

The keys under config are passed to the plugin as they are. allowed_hosts sets the hosts the plugin can reach, and applies only to plugins with the http permission.

Restart pwikit after adding, updating or removing a plugin. A newly installed plugin is disabled on every site. Enable it under Plugins in each site's admin panel.

Writing a plugin ​

Plugins can be written in any language that compiles to WASI, and talk to pwikit through the Extism PDK. In Go:

sh
GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -o plugin.wasm .

plugin.json ​

FieldDescription
namePlugin name, the same as its folder
versionVersion number
apiInterface version, currently 1
title, descriptionName and description shown in the admin panel
modulesModules it provides, such as [{"name": "coinrank"}]. Add "content": true to a module that takes a body
eventsEvents it subscribes to: page.created, page.edited, page.deleted, vote.changed, post.created
permissionskv, pages.read, http
allowed_hostsHosts it can reach
profile_titleWhen set, profiles show a block with this title at the bottom
profile_badgeWhen true, profiles show a badge next to the username
memory_pagesMemory limit in 64 KB pages, 256 by default, at most 1024
timeout_msTime limit per call, 1000 by default, at most 5000

Exports ​

Each export takes a JSON object as input. Its output is rendered as wikitext.

ExportCalled when
moduleA page uses one of the plugin's modules
eventA subscribed event happens
profileA profile shows the plugin's block
badgeA profile shows the plugin's badge

Host functions ​

FunctionPermissionPurpose
kv_get, kv_set, kv_deletekvRead and write the plugin's key-value store on the current site
page_getpages.readGet a public page's title, tags, authors and rating

Example: installing the scpper plugin ​

The scpper plugin shows a member's coin ranking and holdings next to the username on profiles, and provides a wealth ranking module and a tip button. Deploy scpper first, as described in Mounting other programs. These steps assume pwikit is installed in /opt/pwikit.

  1. Download scpper.zip from the releases of pwikit-plugins and unpack it into the plugin folder:

    sh
    sudo apt install unzip
    sudo wget -O /tmp/scpper.zip https://github.com/scpwikicloud/pwikit-plugins/releases/latest/download/scpper.zip
    sudo mkdir -p /opt/pwikit/plugins/scpper
    sudo unzip -o /tmp/scpper.zip -d /opt/pwikit/plugins/scpper
  2. Create the settings file:

    sh
    sudo cp /opt/pwikit/plugins/scpper/config.example.json /opt/pwikit/plugins/scpper/config.json

    scpper_url is the address pwikit reaches scpper at, the same as the upstream of the [[mount]]. scpper_path is the path of the [[mount]] without the trailing /. allowed_hosts holds the host in scpper_url. If you followed Mounting other programs, nothing needs changing.

  3. Restart pwikit:

    sh
    sudo /opt/pwikit/pwikit service restart
  4. In the site's admin panel, open Plugins, tick On this site for scpper, and click Save.

Once enabled, profiles show the coin badge next to the username. Pages can use these modules:

text
[[module CoinRank limit="10"]]
[[module Tip]]

CoinRank shows the wealth ranking. limit sets how many members it lists, 10 by default and at most 100. Tip shows the tip button for the current page and the tips it has received.

To update the plugin, download and unpack it again as in step 1, then restart pwikit. config.json is left as it is.