2026-11-15 16:46:00Ralph Thesen:
Document navbar, admin menu and template_folders plugin hooks
plugins.md ..
@@ 25,6 25,7 @@
- [sidebarpageindex](https://github.com/redimp/otterwiki/tree/main/docs/plugin_examples/plugin_sidebarpageindex) demonstrates the sidebar page index filter and sort hooks.
- [authorsignature](https://github.com/redimp/otterwiki/tree/main/docs/plugin_examples/plugin_authorsignature) adds a footer with the original author and last editor.
- [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.
+
- [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.
## What a plugin is
@@ 168,6 169,13 @@
- `template_html_body_inject(page)` injects HTML before the closing `</body>`.
- `template_html_sidebar_left_inject(page)` appends HTML to the left sidebar (menu and page index).
- `template_html_sidebar_right_inject(page)` appends HTML to the right sidebar (the "On this page" block).
+
- `template_html_navbar_inject(page)` injects HTML into the navbar, after the search field and before the menu button.
+
- `template_html_navbar_dropdown_inject(page)` injects HTML at the top of the navbar dropdown menu.
+
- `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`.
+
+
**Templates**
+
+
- `template_folders()` returns a list of folders with Jinja templates shipped by the plugin, see [Shipping templates](#shipping-templates).
**Per-element rendering**
@@ 203,6 211,61 @@
- `sidebar_page_index_filter_entries(entries, mode)` filters the sidebar page index entries in place.
- `sidebar_page_index_sort_entries(entries, mode)` sorts the sidebar page index entries in place.
+
### Shipping templates
+
+
A plugin that serves its own pages via `url_request` or `url_admin_request`
+
can render them from Jinja templates. For this, the plugin must be a package
+
instead of a single module, because a wheel built from a single module
+
contains only the `.py` file. Hatchling adds all files in the package
+
directory to the wheel, so no extra configuration in `pyproject.toml` is
+
needed:
+
+
```
+
plugin_userinfo/
+
├── pyproject.toml
+
└── otterwiki_userinfo/
+
├── __init__.py
+
└── templates/
+
└── userinfo/
+
└── settings.html
+
```
+
+
The plugin returns its template folder via the `template_folders` hook and
+
renders the template with `flask.render_template`:
+
+
```python
+
import os
+
from flask import render_template
+
from otterwiki.plugins import hookimpl, plugin_manager