Blame

36c0a2 Ralph Thesen 2026-08-30 20:08:01
Add plugins page documenting installation and hooks
1
# Plugins
2
3
An Otter Wiki can be extended with plugins. It uses
4
[pluggy](https://pluggy.readthedocs.io/en/stable/) to expose a set of function
5
hooks that a plugin implements to add or change behaviour, from rewriting
6
markdown before it is rendered to injecting HTML into the sidebar or reacting
7
to page changes.
8
9
> [!NOTE]
10
> The plugin API is experimental and still limited. If you want to write a
11
> plugin and cannot find a matching hook, please open an
12
> [issue](https://github.com/redimp/otterwiki/issues).
13
37b166 Ralph Thesen 2026-08-30 20:08:01
Link the plugins page from the home page
14
## Example plugins
15
16
Same example plugins live in
17
[docs/plugin_examples](https://github.com/redimp/otterwiki/tree/main/docs/plugin_examples)
18
in the source repository. Each is a self-contained package you can copy as a
19
starting point, and they come with a `docker-compose.yaml` for trying them out
20
and a test suite.
21
22
- [noemojis](https://github.com/redimp/otterwiki/tree/main/docs/plugin_examples/plugin_noemojis) removes all emojis from pages.
23
- [htmlinjection](https://github.com/redimp/otterwiki/tree/main/docs/plugin_examples/plugin_htmlinjection) demonstrates the HTML injection and per-element rendering hooks.
24
- [referencingpages](https://github.com/redimp/otterwiki/tree/main/docs/plugin_examples/plugin_referencingpages) shows which pages reference the current page via WikiLinks.
25
- [sidebarpageindex](https://github.com/redimp/otterwiki/tree/main/docs/plugin_examples/plugin_sidebarpageindex) demonstrates the sidebar page index filter and sort hooks.
26
- [authorsignature](https://github.com/redimp/otterwiki/tree/main/docs/plugin_examples/plugin_authorsignature) adds a footer with the original author and last editor.
27
- [redlinks](https://github.com/redimp/otterwiki/tree/main/docs/plugin_examples/plugin_redlinks) marks WikiLinks to non-existent pages in red, like MediaWiki's redlinks.
1f736c Ralph Thesen 2026-11-15 16:46:00
Document navbar, admin menu and template_folders plugin hooks
28
- [userinfo](https://github.com/redimp/otterwiki/tree/main/docs/plugin_examples/plugin_userinfo) shows the logged-in user in the navbar, optionally with the Gravatar icon, and comes with an admin page. It demonstrates the navbar and admin menu hooks, and how a plugin ships its own templates.
37b166 Ralph Thesen 2026-08-30 20:08:01
Link the plugins page from the home page
29
30
36c0a2 Ralph Thesen 2026-08-30 20:08:01
Add plugins page documenting installation and hooks
31
## What a plugin is
32
33
A plugin is a normal, pip-installable Python package that registers one or more
34
hook implementations. In practice that means three things:
35
36
- a class whose methods are decorated with `@hookimpl`,
37
- a call to `plugin_manager.register(...)` so the wiki finds it,
38
- an `otterwiki` entry point in the package metadata.
39
40
The smallest complete example, the `noemojis` plugin, strips emojis from every
41
page before it is rendered:
42
43
```python
44
from otterwiki.plugins import hookimpl, plugin_manager
45
46
class NoEmojiPlugin:
47
@hookimpl
48
def renderer_markdown_preprocess(self, md):
49
return self.emojis.sub('', md)
50
51
# needed so the plugin_manager finds the plugin
52
plugin_manager.register(NoEmojiPlugin())
53
```
54
55
with a `pyproject.toml` that declares the entry point:
56
57
```toml
58
[project.entry-points.otterwiki]
59
noemojis = "otterwiki_noemojis"
60
```
61
62
A plugin that surfaces `info()` and `help()` also appears in the in-app plugin
63
help at [/-/help/plugins](/-/help/plugins), next to the built-in embeddings.
64
65
## Installing a plugin
66
67
A plugin must be installed into the same (virtual) environment that runs the
68
flask app.
69
70
### In the docker image
71
72
On container start `entrypoint.sh` installs every plugin directory it finds
73
under `/app-data/plugins/` and `/plugins/` with `pip install -U .`. So there
74
are two ways to deploy a plugin:
75
76
- drop the plugin directory into `plugins/` inside the volume that already
77
holds your `app-data` (alongside `db.sqlite` and `repository`), or
78
- keep your plugins in a separate directory and mount it into the container at
79
`/plugins`.
80
81
For example, mounting a plugins directory next to the usual app-data volume:
82
83
```yaml
84
services:
85
otterwiki:
86
image: redimp/otterwiki:2
87
volumes:
88
- ./app-data:/app-data
89
- ./plugins:/plugins
90
```
91
92
> [!NOTE]
93
> A plugin with dependencies that are not already in the image will fail to
94
> install. In that case build a custom image that bundles the plugin and its
95
> requirements. In environments with `SELINUX=enforcing` the bind mounts need
96
> adjusting, see the [[FAQ|FAQ#environments-with-selinux]].
97
98
### From a source install
99
100
Activate the virtual environment that runs the app and install the plugin
101
directory into it:
102
103
```bash
104
venv/bin/pip install .
105
```
106
107
### Uninstalling
108
109
From a source install run `pip uninstall <plugin-name>`. For the docker image,
110
remove the plugin directory and recreate the container for a clean environment.
111
112
## Developing Plugins
113
64f2a5 Ralph Thesen 2026-08-30 20:24:39
Add a Developing Plugins section to the plugins page
114
The quickest way to start is to copy one of the [example plugins](#example-plugins)
115
above and adapt it: each is a minimal, self-contained package with a working
116
`pyproject.toml`, the `otterwiki` entry point and a test to build on.
117
118
A plugin package is a directory holding the module and a `pyproject.toml`. In the
119
module you implement the hooks you need as methods on a class, decorate each with
120
`@hookimpl`, and register an instance with `plugin_manager.register(...)` (the
121
[What a plugin is](#what-a-plugin-is) example shows the smallest version).
122
Implement only the hooks you need; the [Available hooks](#available-hooks) list
123
below summarises them, and `otterwiki/plugins.py` carries the full signatures.
124
125
A few things worth knowing when writing a hook:
126
127
- Plugins that need the Flask app, database or git storage receive them through
128
the `setup(app, db, storage)` hook; rendering-only plugins can ignore it.
129
- Some hooks are **chained**, each plugin's return value feeding the next, so the
130
order plugins load in matters. The markdown and HTML pre/post-processing hooks
131
(such as `renderer_markdown_preprocess`) work this way.
132
- Some hooks return the **first non-`None`** result and then stop, for example
133
`embedding_render`, so a plugin can claim a single embedding name.
134
- The two `sidebar_page_index_*` hooks **mutate the entries list in place**
135
rather than returning a new one.
136
137
For the full mechanism, the hookspec docstrings in
138
[otterwiki/plugins.py](https://github.com/redimp/otterwiki/blob/main/otterwiki/plugins.py)
139
are the reference, and the [example plugins](#example-plugins) above show each
140
hook in use.
36c0a2 Ralph Thesen 2026-08-30 20:08:01
Add plugins page documenting installation and hooks
141
142
### Available hooks
143
144
The authoritative list of hooks, with full signatures and documentation, is the
145
`OtterWikiPluginSpec` class in
146
[otterwiki/plugins.py](https://github.com/redimp/otterwiki/blob/main/otterwiki/plugins.py).
147
A plugin implements only the hooks it needs. Grouped by purpose:
148
149
**Setup**
150
151
- `setup(app, db, storage)` receives the Flask app, database and git storage to initialise the plugin.
152
153
**Rendering (pre/post processing)**
154
155
- `renderer_markdown_preprocess(md)` transforms the raw markdown before rendering (chained across plugins).
156
- `renderer_html_postprocess(html)` transforms the HTML after the page has been rendered.
157
- `renderer_javascript()` adds JavaScript to the rendered page.
158
- `page_view_htmlcontent_postprocess(html, page)` transforms a page's rendered content just before display.
159
- `page_render_context(page, preview)` receives the page currently being rendered, and whether it is a preview.
160
161
**Embeddings**
162
163
- `embedding_parse(embedding, options, args)` parses an embedding and returns its HTML.
164
- `embedding_render(embedding, args)` renders a `{{name ...}}` embedding to HTML.
165
166
**Template injection points**
167
168
- `template_html_head_inject(page)` injects HTML into the `<head>`.
169
- `template_html_body_inject(page)` injects HTML before the closing `</body>`.
170
- `template_html_sidebar_left_inject(page)` appends HTML to the left sidebar (menu and page index).
171
- `template_html_sidebar_right_inject(page)` appends HTML to the right sidebar (the "On this page" block).
1f736c Ralph Thesen 2026-11-15 16:46:00
Document navbar, admin menu and template_folders plugin hooks
172
- `template_html_navbar_inject(page)` injects HTML into the navbar, after the search field and before the menu button.
173
- `template_html_navbar_dropdown_inject(page)` injects HTML at the top of the navbar dropdown menu.
174
- `template_html_admin_menu_inject()` appends HTML to the admin section of the settings sidebar, e.g. a link to a page served via `url_admin_request`.
175
176
**Templates**
177
178
- `template_folders()` returns a list of folders with Jinja templates shipped by the plugin, see [Shipping templates](#shipping-templates).
36c0a2 Ralph Thesen 2026-08-30 20:08:01
Add plugins page documenting installation and hooks
179
180
**Per-element rendering**
181
182
- `renderer_process_link(...)` modifies each rendered markdown link.
183
- `renderer_process_image(...)` modifies each rendered image.
184
- `renderer_process_heading(...)` modifies each rendered heading.
185
- `renderer_process_wikilink(...)` modifies each rendered WikiLink.
186
187
**Repository and page events**
188
189
- `repository_changed(changed_files)` reacts to any repository change, including the git web server and automatic pulls (read-only).
190
- `page_saved(pagepath, content, author, message)` runs after a page's content changed.
191
- `page_deleted(pagepath, author, message)` runs after a page was deleted.
192
- `page_renamed(old_pagepath, new_pagepath, author, message)` runs after a page was renamed.
193
194
**Info and help**
195
196
- `info()` returns `(name, description, category)` used to group the plugin in the user help.
197
- `help(plugin)` returns the plugin's documentation shown under `/-/help`.
198
- `help_category_prelude(category)` returns introductory text for a help category.
199
200
**Static CSS**
201
202
- `static_css()` returns CSS added to every page via the layout template.
203
204
**URL routes**
205
206
- `url_request(plugin, extra, method, values)` handles requests to `/-/plugin/<name>/<extra>`.
207
- `url_admin_request(plugin, extra, method, values)` handles admin requests to `/-/admin/plugin/<name>/<extra>`.
208
209
**Sidebar page index**
210
211
- `sidebar_page_index_filter_entries(entries, mode)` filters the sidebar page index entries in place.
212
- `sidebar_page_index_sort_entries(entries, mode)` sorts the sidebar page index entries in place.
64f2a5 Ralph Thesen 2026-08-30 20:24:39
Add a Developing Plugins section to the plugins page
213
1f736c Ralph Thesen 2026-11-15 16:46:00
Document navbar, admin menu and template_folders plugin hooks
214
### Shipping templates
215
216
A plugin that serves its own pages via `url_request` or `url_admin_request`
217
can render them from Jinja templates. For this, the plugin must be a package
218
instead of a single module, because a wheel built from a single module
219
contains only the `.py` file. Hatchling adds all files in the package
220
directory to the wheel, so no extra configuration in `pyproject.toml` is
221
needed:
222
223
```
224
plugin_userinfo/
225
├── pyproject.toml
226
└── otterwiki_userinfo/
227
├── __init__.py
228
└── templates/
229
└── userinfo/
230
└── settings.html
231
```
232
233
The plugin returns its template folder via the `template_folders` hook and
234
renders the template with `flask.render_template`:
235
236
```python
237
import os
238
from flask import render_template
239
from otterwiki.plugins import hookimpl, plugin_manager
240
241
class UserInfo:
242
@hookimpl
243
def template_folders(self):
244
return [os.path.join(os.path.dirname(__file__), "templates")]
245
246
@hookimpl
247
def url_admin_request(self, plugin, extra, method="GET", values=None):
248
if plugin != "userinfo" or extra != "settings":
249
return None
250
return render_template("userinfo/settings.html", title="User Info")
251
252
plugin_manager.register(UserInfo())
253
```
254
255
An Otter Wiki searches the plugin folders after its own templates:
256
257
- A plugin cannot override a core template. A plugin file named `layout.html`
258
has no effect.
259
- A plugin template can extend a core template. For example, an admin page
260
that starts with `{% extends "settings.html" %}` has the same layout and
261
sidebar as the other admin pages.
262
263
To prevent name conflicts between plugins, put the templates in a subfolder
264
named after the plugin, e.g. `templates/userinfo/`, and render them as
265
`render_template("userinfo/settings.html")`. The
266
[userinfo](https://github.com/redimp/otterwiki/tree/main/docs/plugin_examples/plugin_userinfo)
267
example plugin shows the complete setup.
268
64f2a5 Ralph Thesen 2026-08-30 20:24:39
Add a Developing Plugins section to the plugins page
269
### Testing a plugin
270
271
You do not need to install a plugin to test it. The example plugins use an
272
`example_plugin_loader` fixture (in
273
[docs/plugin_examples/tests](https://github.com/redimp/otterwiki/tree/main/docs/plugin_examples/tests))
274
that loads a plugin straight from its directory and unregisters it again on
275
teardown. Add a `test_<name>.py` next to the existing ones, load your plugin with
276
`example_plugin_loader("plugin_<name>")`, and if it implements `setup()` call it
1f736c Ralph Thesen 2026-11-15 16:46:00
Document navbar, admin menu and template_folders plugin hooks
277
on the loaded instance. The fixture loads single modules (`otterwiki_<name>.py`)
278
and packages (`otterwiki_<name>/__init__.py`). Run the suite with:
64f2a5 Ralph Thesen 2026-08-30 20:24:39
Add a Developing Plugins section to the plugins page
279
280
```bash
281
OTTERWIKI_SETTINGS="" venv/bin/pytest docs/plugin_examples/tests
282
```