Extensions
Wikven runs a real MediaWiki at build time, so a MediaWiki extension works the way it always does — as long as what it does can be finished before the site is published. This page is about which extensions you can have, and how to get one that is not already there.
Enabling an extension
List it in .wikven.yaml by name. Extensions that ship inside Wikven need nothing else:
extensions:
- ParserFunctions
- SyntaxHighlight_GeSHi
A name Wikven cannot find on disk is skipped with a warning in the build log rather than failing the build, so a typo shows up as an extension that quietly did nothing. Anything not shipped has to say where it comes from, under WikvenRepositories.
What is already there
The Wikven image carries everything bundled with MediaWiki — ParserFunctions, Cite, Gadgets, SyntaxHighlight_GeSHi, TemplateStyles and the rest — plus three Wikven adds for what a static site needs:
- SifterSearch
- Client-side search. Enabled by default on every site, so search works with no configuration at all.
- Translate
- Multilingual pages, driven from your source tree. See Translating.
- UniversalLanguageSelector
- Translate's own dependency, and where bundled webfonts come from.
The last two are loaded only if you list them; SifterSearch is loaded for you. To see exactly what a given image holds, ask it:
docker run --rm --entrypoint ls ghcr.io/chaotic-ground/wikven extensions
docker run --rm --entrypoint ls ghcr.io/chaotic-ground/wikven skins
Anything else
An extension that is not in the image is fetched at build time from a source you declare — a tarball, a Git repository, or a Composer package. The name still goes in extensions; WikvenRepositories only says where to get it:
extensions:
- TabberNeue
config:
WikvenRepositories:
TabberNeue:
repository: https://github.com/StarCitizenTools/mediawiki-extensions-TabberNeue.git
reference: v4.0.0
This documentation site fetches TabberNeue exactly like that — the tabs on Getting Started are it — along with MobileFrontend, which MinervaNeue leans on. See WikvenRepositories for the three ways to name a source, the host tools each one needs, and why to pin what you fetch.
What will not work
An extension has to do its work during the build, because the published site is files on a host that runs no PHP. That rules out a whole class of them, however well they behave on a live wiki:
- Anything that edits. VisualEditor, WikiEditor and CodeEditor have nothing to save to.
- Anything that answers a request. An extension whose feature is a special page, an API module, or a query run when a reader clicks, has no server to run on. Whatever it renders into a page at build time is all that survives.
- Anything keyed to a reader. There are no accounts, no preferences and no sessions in an export, so notifications, watchlists and per-user settings have nothing to work with.
Extensions that only change how wikitext renders — parser tags, parser functions, styling, templating — are the ones that work best, because their whole job is over by the time the page is written out.
An extension of your own can also be made to survive a build deliberately; Writing an extension is the contract for that.