Blame
|
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 | ||||||||
|
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. |
|||||||
|
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. |
||||||
|
29 | |||||||
| 30 | ||||||||
|
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 | ||||||||
|
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. |
|||||||
|
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). |
|||||||
|
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). |
|||||||
|
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. |
|||||||
|
213 | |||||||
|
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 | ||||||||
|
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 |
|||||||
|
277 | on the loaded instance. The fixture loads single modules (`otterwiki_<name>.py`) |
||||||
| 278 | and packages (`otterwiki_<name>/__init__.py`). Run the suite with: |
|||||||
|
279 | |||||||
| 280 | ```bash |
|||||||
| 281 | OTTERWIKI_SETTINGS="" venv/bin/pytest docs/plugin_examples/tests |
|||||||
| 282 | ``` |
|||||||
