Configuration
Configuration lives in a .wikven.yaml file in your source directory. It follows the same shape as MediaWiki's own YAML settings format: a top-level extensions list, a skins list, and a config map.
The file name is flexible. Wikven accepts .wikven.yaml, .wikven.yml or .wikven.json, and the same three without the leading dot (wikven.yaml, wikven.yml, wikven.json); the .json forms use the same structure, since YAML is a superset of JSON. If more than one is present the first wins, in that order, and the rest are ignored with a warning, so a dotted name beats a plain one, YAML beats JSON, and .yaml beats .yml.
Wikven ships its own defaults (a sensible MediaWiki configuration for a static wiki) and loads your file on top of them, so anything you set here overrides the default. The defaults live in a default.yml that uses this same format; see #Defaults below.
extensions:
- SyntaxHighlight_GeSHi
- ParserFunctions
skins:
- Timeless
config:
Sitename: Wikven
WikvenEditUrl: https://github.com/yourname/some-repository/edit/branch-name/path/to/$1
WikvenHistoryUrl: https://github.com/yourname/some-repository/commits/branch-name/path/to/$1
extensions
A list of extension names to load. Bundled extensions work by name alone; a name that is not bundled is treated as third-party and fetched from a source you declare in WikvenRepositories.
skins
A list of skin names to enable. The first one is used as the default skin. As with extensions, a non-bundled name is fetched from WikvenRepositories. See Skins.
config
A map of configuration variables, each named without the wg prefix, just like in MediaWiki's YAML settings format. Any configuration setting can be defined here, including Wikven's own variables such as WikvenMainPage, WikvenEditUrl, WikvenHistoryUrl, WikvenViewSourceUrl, WikvenVersionPage, WikvenFooterUrl, WikvenLogos, and WikvenRepositories.
WikvenLogos
The site's header logos. It mirrors MediaWiki's $wgLogos, with the same keys (icon, 1x, svg, wordmark, and so on), except each value is the name of an image file in your source directory rather than a URL:
config:
WikvenLogos:
icon: logo.svg
The values are file names rather than URLs because the file's address is decided by the build, not by you. Each named file is uploaded into the File: namespace like any other source image, and Wikven points $wgLogos at the upload for you, so you only name the file. The export then copies the logo to a single shared file next to the HTML and rewrites the reference to it, the same as for any other image, so the logo is not embedded into every page.
Wikven also ships a small default favicon so browsers do not 404 on /favicon.ico; override it with config.Favicon (a URL or a data URI).
WikvenEditUrl, WikvenHistoryUrl and WikvenViewSourceUrl
The targets the "Edit", "View history" and "View source" links point at, so a reader can jump from a rendered page to its source in your repository. In each URL, $1 is replaced with the page's source file name relative to your source directory, including its extension. A page whose title carries its own content model keeps that name verbatim (MediaWiki:Common.css, MediaWiki:Common.js, a .json config page, a Module: page, ...); every other page is a .wikitext file, so a normal page becomes Getting Started.wikitext. Leave any of them unset to drop that link; a generated page (such as the Version page) has no source file, so these links are omitted for it.
WikvenMainPage
The title of the page used as the site root, written as index.html and served at the top of the site. Defaults to index, so naming your entry file index.wikitext works with no configuration. The page must be one you imported; the build fails if it is missing.
WikvenVersionPage
The title of an auto-generated page (mirroring Special:Version) that lists the installed software, extensions and skins, linked from the footer. Defaults to Version. Set it empty to disable the page; a source page of the same name takes precedence over the generated one.
WikvenFooterUrl
A link added to the site footer, pointing at your project (typically its repository). The footer shows the host name for known forges (GitHub, GitLab, Codeberg, ...).
WikvenRepositories
Sources for the third-party extensions and skins you list in extensions and skins. The lists stay plain names (the shape MediaWiki itself uses); this map says where to get the ones that are not bundled with wikven. They are fetched at build time, before MediaWiki loads them. Whether an entry is an extension or a skin is taken from which list its name appears in, so you never write the name twice.
Each entry chooses one of three methods by the key it carries:
config:
WikvenRepositories:
# 1. A tarball, e.g. from Special:ExtensionDistributor, whose archive already
# bundles the extension's dependencies. Add sha256 to verify the download.
Foo:
tarball: https://extdist.wmflabs.org/dist/extensions/Foo-REL1_45-abc1234.tar.gz
sha256: 4f5e... # 64 hex characters; the build aborts on a mismatch
# 2. A Git repository. Pin it with commit (an exact SHA, reproducible) or
# reference (a tag or branch). Add composer: true to run Composer inside
# the cloned directory.
Bar:
repository: https://github.com/example/Bar.git
commit: 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b
composer: true
# 3. A Composer package, resolved through MediaWiki's composer.local.json.
SemanticMediaWiki:
package: mediawiki/semantic-media-wiki:~4.1
A name in WikvenRepositories that is already bundled with wikven is left untouched. A name that is not also listed in extensions or skins is an error.
Each method needs a host tool present at build time: tarball uses curl and tar, repository uses git (and Composer when composer: true), and package uses Composer. The Docker image bundles all of these; with the standalone binary they must be on your PATH.
The build downloads and runs the code you name here, with network access: a cloned extension's PHP and any Composer scripts execute during the build. Only declare sources you trust. For a tamper-evident, reproducible build, pin a tarball with sha256 and a repository with commit (an exact SHA); a mutable reference tag/branch or a floating package constraint can change underneath you.
This very site fetches TabberNeue this way (see its .wikven.yaml): the tabbed Docker/binary command examples on Getting Started are rendered by the fetched extension. (TemplateStyles, used by this site's templates, is bundled in MediaWiki and so needs no source here.)
ContentNamespaces
A standard MediaWiki setting ($wgContentNamespaces) that decides which pages wikven exports: only pages in a content namespace are written to the static site. Wikven defaults it to [0, 6], the main and File: namespaces, so file description pages are exported without dumping every Template: or MediaWiki: page. Add the Category namespace (14) to export category pages too; see Pages#Categories. Because a config value replaces the default rather than extending it, list the full set you want, including the defaults you keep.
Defaults
Before reading your .wikven.yaml, Wikven applies its own defaults from a default.yml bundled with wikven. It is written in the same format as your configuration, so it doubles as a reference for what Wikven sets for you: the site name, page titles kept as written, InstantCommons, local image uploads (including SVG), the Vector 2022 skin options, and so on. It also ships an extensions and a skins default, so every site gets SifterSearch search and the Vector skin without listing them. Your .wikven.yaml is merged on top, with your config keys overriding the defaults and your extensions and skins appended.
Titles are kept as written (rather than first-letter-capitalized, MediaWiki's default) so the entry page can be the lowercase index, which the build writes as index.html, the file a static host serves at the site root. The file is otherwise commented; each comment notes why Wikven sets that value.
To see the current defaults, read the bundled default.yml. From the Docker image:
docker run --rm --entrypoint cat ghcr.io/chaotic-ground/wikven extensions/Wikven/default.yml
It is also in the repository.