Wikven

Skins

Translate this page
Other languages:

You can choose bundled skins in .wikven.yaml.

Supported skins

Wikven supports three skins. This documentation site is built with all three, so every change is exercised in each of them.

  • Vector (default; Vector selects the skin's vector-2022 variant, Vector 2022)
  • MinervaNeue (mobile-oriented)
  • Citizen (third-party, fetched at build time)

Any other skin is untested rather than refused: every skin bundled with MediaWiki is available by name, MonoBook among them, and a third-party skin can be fetched like Citizen is.

Minerva needs more said about it than the other two, a build working around parts of the skin rather than configuring them. That is collected in the appendix rather than here.

Configuring the skin

skins says which skins to build. Wikven builds Vector whatever else you list, so naming another one adds it rather than replaces it: 

skins:
  - MinervaNeue

To build without it, set WikvenBuildVector to false. That setting is a stopgap: in 2.0 a skins list will replace the default rather than add to it, so a site that wants to keep Vector should list it too. Adding Vector to skins now changes nothing, since it is built anyway, and keeps the site the same across the upgrade. 

skins:
  - Vector
  - MinervaNeue

Which of them the site is read in is a separate question, and MediaWiki already has the setting for it. Name the skin in config under DefaultSkin, by its canonical name -- which is what MediaWiki calls a skin, and is not always what you listed it by: minerva for MinervaNeue, vector-2022 for Vector. 

skins:
  - MinervaNeue
config:
  DefaultSkin: minerva

Without it the site is read in the first skin built, which is the only answer a site with one skin needs. A DefaultSkin naming a skin the site does not build is reported and ignored, since a default nothing renders would leave the output root with no pages in it.

Building more than one skin

List more than one skin and the site is built in every one of them, and the reader picks. This documentation site does that with all three. It is one line of configuration and rather more than one line of consequences, so they are worth knowing:

  • The site is rendered once per skin. A bake with three skins does three full renders and writes about three times as many files. The renders run beside each other, one per processor the build is allowed, so the time they add is what the machine has no processor to spare for: given three, a three-skin bake costs about what a one-skin bake does; given one — or with WIKVEN_BUILD_JOBS set to 1 — about three times as much.
  • Each skin gets its own copy of every page. The one the site is read in renders into the output root, as a single-skin site does, and every other renders into a directory named after it: dist/citizen/Getting_Started.html beside dist/Getting_Started.html. The copies are complete, down to their own search index, so a reader who chooses a skin stays in it while browsing and while searching.
  • The copies are kept out of search engines. Only the main skin's pages are indexable; the others are rendered noindex, so a search engine is not offered the same page three times.
  • Every page gains a skin switcher. Where it appears is up to the skin: Vector puts it in the appearance menu, Citizen in its preferences panel, and any other skin in the toolbox. A reader with no JavaScript still gets the plain list of links. MinervaNeue is the exception: the toolbox it would take is its page-actions menu, and which skin to read the site in is not an action on a page, so an article in it carries no switcher and the list is on the Settings page instead. Its main menu carries the site's own navigation and a link to that page.

With a single skin there is no switcher and no copy: the output is exactly what it was before.

Settings

The build writes one page of its own for the reader: Settings, named by the WikvenSettingsPage setting. It stands in for the preferences a live wiki would offer, which a static site has no server for, and holds the choices that are the reader's rather than yours:

  • which skin to read the site in, on a site built with more than one; and
  • the colour theme (and text size, where the skin has one), which comes from MobileFrontend's own display controls, so this part appears only on a site that has MobileFrontend enabled.

Both choices are kept in the reader's browser, for that site alone, with no account and nothing stored on any server. Write a source page named Settings and yours is used instead; set WikvenSettingsPage empty and no page is written and nothing links to one.

Third-party skins

A skin that is not bundled can be listed in skins too, with its source declared in the WikvenRepositories map. It is fetched at build time and may be the default like any other. This documentation site fetches Citizen this way, offered alongside the other two. 

skins:
  - Example
config:
  WikvenRepositories:
    Example:
      repository: https://github.com/example/Example.git
      reference: REL1_46

Skin-specific configuration

Use the config map. 

config:
  VectorResponsive: false

A setting reaches the skin the same way any other does, but it only does something if the skin still reads it in a build. Minerva is the one place where most do not; see Minerva settings in the appendix before reaching for one.

Appendix: Minerva

Minerva and MobileFrontend

MinervaNeue is bundled with MediaWiki; MobileFrontend, which it grew up alongside, is not. Without it the skin skips its own initMobile.js and loses what that sets up, the table of contents toggle among it. Fetch the pair if you enable Minerva. This site does, so the recommended configuration is the one every build renders. 

skins:
  - MinervaNeue
extensions:
  - MobileFrontend
config:
  WikvenRepositories:
    MobileFrontend:
      repository: https://github.com/wikimedia/mediawiki-extensions-MobileFrontend.git
      reference: REL1_46

Wikven renders Minerva without it as well: the entries it offers that a static host cannot serve are dropped either way.

How Minerva is supported

Minerva is built and exercised like the other two, but more of that support is Wikven working around the skin than configuring it. Minerva builds its main menu from its own definitions rather than from MediaWiki:Sidebar, and several of its controls expect MobileFrontend or a live wiki behind them, so the build stands in for both:

  • The site's own navigation is written into the main menu of every rendered page, there being no sidebar section the skin would read it from.
  • Random, Recent changes, Special pages and Preferences are hidden with a stylesheet rather than dropped: the skin inserts them unconditionally, so the anchors are still in the exported HTML.
  • Community portal is dropped properly, through the message the skin already checks.
  • The colour theme and the skin to read in are on the baked Settings page, the skin's own being Special:MobileOptions.
  • The language button is hidden, its overlay being MobileFrontend's.
  • Without MobileFrontend the table of contents arrives collapsed and the toggle that would open it is never drawn, so a stylesheet opens it again.

A reader meets none of this. It is worth knowing before changing Minerva's chrome, though: a change there usually lands in maintenance/fillMinervaMenu.php or resources/skins.minerva.styles.less rather than in configuration.

Minerva settings

Most of the $wgMinerva* settings do nothing in a build, whether or not MobileFrontend is installed. Ten of the sixteen the skin declares are registered as MobileFrontend features and read back in SkinOptions::setMinervaSkinOptions(), which runs from the RequestContextCreateSkinMobile hook — and MobileFrontend fires that only once it has decided to serve a mobile view, which takes a mobile domain, a mobile device, or useformat=mobile. A bake is none of those, so the skin options keep the defaults compiled into them and these settings are inert: MinervaShowCategories, MinervaPageIssuesNewTreatment, MinervaTalkAtTop, MinervaDonateLink, MinervaDonateBanner, MinervaHistoryInPageActions, MinervaOverflowInPageActions, MinervaAdvancedMainMenu, MinervaPersonalMenu and MinervaNightMode.

The other six the skin reads off the configuration itself, so they behave as documented: MinervaEnableSiteNotice, MinervaAlwaysShowLanguageButton, MinervaDownloadNamespaces, MinervaNightModeOptions, MinervaTypeahead and MinervaABSamplingRate. MinervaTypeahead is the one worth reaching for: the skin's typeahead runs on the static index rather than on the search API the setting names, so its options are read while its API URLs are not, and the empty thumbnail column is turned off there — see Searching. MinervaABSamplingRate has nothing to act on, there being no A/B bucketing to sample. The language button is hidden either way, its overlay being MobileFrontend's.

What the inert ones would have configured, Wikven supplies its own way where it can: the colour theme is on the Settings page the build writes in place of Special:MobileOptions, and the site's own navigation is written into the main menu of every rendered page.

← Images
Searching →
Retrieved from "https://chaotic-ground.github.io/wikven/Skins/en.html"