HowItWorks:MediaWiki

Explains how things actually work — part of our technology dissections collection.

MediaWiki is the free, open-source wiki engine behind tens of thousands of websites — such as Wikipedia, Wikidata — and this very site: RonzzWikiBase.

What is a wiki engine?

Wiki engine is the software behind a wiki: a website hosting static pages, usually informative, which contributors can edit within their browser, with every change tracked and reversible, hence allowing contributions from a large number of editors located anywhere in the world. In its most radical form, e.g., Wikipedia, anyone reading the page can make edits, quickly correcting errors and updating pages.

A wiki engine's most essential job is to store wiki pages in a database, and pull them up for contributors to edit or for the renderer to render pages to HTML for readers on demand. For real-world application, it must also handle authentication, caching, indexing&searching and other auxiliary performance/security needs.

MediaWiki, one of the most well-known wiki engines, was originally built as a summer project by early Wikipedia contributor Magnus Manske in 2001 to support a growing Wikipedia. It went through multiple full/partial rewrites — Lee Daniel Crocker rewrote Manske's engine as "Phase III" in 2002 — and the software was renamed "MediaWiki" in 2003, with the first numbered release, 1.1, following in December 2003. It is today used by tens of thousands of wikis, private and public.

Components and interactions

MediaWiki in action

There are two core flows in MediaWiki: page view and page write.

Page view

Page write

MediaWiki has supported automatic merging of non-interfering edit conflicts since version 1.3 (2004): when someone else saves a change that does not overlap yours, MediaWiki merges the two edits instead of forcing a conflict screen.

Key design decisions

Principal content is created and stored in wikitext

MediaWiki stores pages as wikitext in the database; the rendered HTML exists only as cache.

Why?

MediaWiki software is conceived for wikis, which in their most radical form allows editing from anyone, including odd-time readers lacking any computer programming knowledge correcting a spelling mistake. Therefore, an intuitive editing experience is extremely important in MediaWiki.

HTML, the standard markup language for web content, is verbose and hostile to non-programmers. Every element, body text, image, or list elements need tags, usually two, sometimes more. A misplaced or missing tag may prevent the entire page from being rendered correctly. To eliminate the need for direct HTML editing, Wikitext, a lightweight markup language directly parsable into HTML, was created.

On MediaWiki instances, users edit wikitext. As frequent editing is expected, it is only natural to also store content in this format, not HTML, to avoid resource-intensive parsing and deparsing on each revision.

As can be seen in the above diagram. Caching on first read ensures that storing content as wikitext inflicts no performance overhead on read. The content is parsed once after every new revision, lazily on read.

The parser stays stable, always stable

The MediaWiki parser, which parses wikitext into HTML, is arguably the most essential part of MediaWiki core. Every single wiki page depends on it.

As such, any proposed changes to the parser must survive extensive scrutiny before being implemented. The wikitext markup MediaWiki uses descends from earlier wiki engines — notably UseModWiki, which ran Wikipedia before MediaWiki and influenced its markup — and grew organically in response to user demand over the years. To this day the MediaWiki-flavoured wikitext has not received a formal specification; the closest thing to one is the parser test suite, which mediawiki.org describes as "the authoritative source for Wikitext markup compatibility testing". There is however an unofficial spec, jokingly phrased: "whatever the parser spits out, plus a few hundred test cases".

The solution to the problem was to develop a second parser alongside the primary parser. The second parser, as MediaWiki contributors agreed, would not take on any actual functionality until it is proven reliable. The development of the second parser, Parsoid, began in 2012, originally with the aim of supporting MediaWiki's new visual editor. Originally written in JavaScript (Node.js), it was ported to PHP in 2019. At the time of writing (2026-08), Parsoid is planned to become the default parser for the entire MediaWiki system — the "unified parser" — in version 1.47, scheduled for November 2026.

Templates, lots of templates

Templates let a wiki define something once and reuse it everywhere — a navigation box, a banner, an infobox. A page calls a template with {{Name}}, and the template's content is expanded into the page at read time.

Template support was introduced in 2004: Tim Starling added templates in MediaWiki 1.2, and version 1.3 (August 2004) expanded them with parameters and moved them out of the MediaWiki: namespace into a dedicated Template namespace. For large instances like Wikipedia, this was transformative: the same boilerplate, which used to be copied onto thousands of articles, now only need to be defined once, making error correction and updates much easier. Over time, templates, as one of the most used features in MediaWiki, were enhanced with programming-like constructs: the ParserFunctions extension provides conditional and expression parser functions such as {{#if:…}} and {{#switch:…}}, turning templates into a miniature — if awkward — programming language.

There was however a price to pay: Template-heavy pages became slow to parse, really slow. MediaWiki mitigated the issue in MediaWiki 1.12 (2008) by rewriting the preprocessor: the new two-pass preprocessor parses templates into a tree and skips the branches that are never used, such as the un-taken cases of a {{#switch:}}. Template-heavy pages got much faster, without any change to the markup.

Here is a minimal example:

Template code to be defined once on Template:Welcome	Include code to be written on pages that use it	Expansion result what the reader sees
'''Welcome, {{{name|guest}}}!''' {{{message}}}	{{Welcome|name=Alice|message=We're glad you're here.}}	Welcome, Alice! We're glad you're here.

The {{{name|guest}}} syntax gives the parameter a default value: calling {{Welcome|message=Welcome back.}} without a name expands to Welcome, guest! Welcome back.

Skins separate content from presentation

A skin is the frame around the content: the header, footer and sidebar, plus the CSS and JavaScript that style them. It allows the same wikitext content, itself containing little formatting information, to be rendered into beautiful webpages for readers.

Skins are as old as MediaWiki itself — the Phase II script of 2001 already supported them. In version 1.3 (August 2004), MonoBook was introduced as the new default layout.

The skin system separates presentation from content. It ensures 3 things:

• Uniformity across pages: The same navigation, branding, and layout are applied to every page without touching the article text. A wiki can change its entire visual identity by swapping a single skin, without touching the actual content of any article.
• User preference: Registered users can choose their own skin (e.g., MonoBook, Vector, or modern variants) independently of the wiki's default, personalising their experience without impacting others.
• Device adaptation: Skins allow the same underlying HTML to be styled for desktop, tablet, and mobile differently.

The technical implementation of skins evolved over time. Early skins were built on PHPTAL-based templates; MediaWiki 1.4 (2005) reworked the skin system around the SkinTemplate class and a QuickTemplate system, removing the PHPTAL dependency and giving skins a cleaner, data-oriented interface. More recently, version 1.35 (2020) introduced the SkinMustache class, which allows skins to be defined with logicless Mustache templates, making them easier for front-end developers to customize without touching PHP.

The main challenge with complex skins is caching complexity. The same page can look drastically differently depending on which skin is being used, so the cached HTML for one skin cannot be reused for another. As such, large instances allowing arbitrary user skins suffer inevitably from cache fragmentation: a page does not just need to be cached once, but numerous times for each supported skin. Moreover, skins that heavily rely on JavaScript for interactivity (e.g., the sticky header in Vector 2022) must be carefully optimised for loading time: a poorly optimized skin can add hundreds of milliseconds to page rendering, resulting in a sluggish feeling on slower devices.

The skin hooks used to inject custom data into page output also carry a maintenance cost: every hook adds complexity and can break when the skin is updated, making maintenance a challenge for large instances like Wikipedia, which now maintains a tightly controlled set of skins to ensure consistent performance and accessibility across billions of pageviews.

The ResourceLoader, introduced in MediaWiki 1.17 (2011), allows skins to declare and load their CSS and JavaScript modules on demand, with minification and concatenation built in, improving performance.

Extensions plug in; the core stays stable and small

MediaWiki's core is deliberately small: it contains the bare-minimum necessary for a running wiki instance. Additional functionalities live in extensions. They attach to the core through hooks — places where third-party code can run before, after, or instead of MediaWiki's own behaviour for a given event. Some hooks even let an extension add new wikitext syntax of its own.

The hook system allows MediaWiki to respond to user demands rapidly while staying robust. Adding extra functionalities means enhancing existing extensions or writing new ones, not editing the core.

Caching, lots of caching

PHP has no concept of connection pooling or application memory. Without a proper caching system, PHP backend performance becomes catastrophic at scale, as every request must execute PHP code through the entire program logic.

For optimal performance, MediaWiki uses multiple layers of caches, each sitting at a different point in the request pipeline:

The key challenge for caching MediaWiki is staleness. On large public instances like Wikipedia with permissive editing permissions, pages are being edited every second, which means even caches created in the minute may become stale.

To solve the problem, MediaWiki attaches a timestamp to all cached content. At render time, that timestamp is compared with the timestamp of the last revision, and the cached content is only served if the cache is newer than the last revision.

Try it yourself

All commands below were verified to work at the time of writing (2026-08-28) against this wiki, which runs MediaWiki 1.46.0 (confirmed via the siteinfo API below).

# Which version is this wiki running?
curl -s "https://wikibase.ronzz.org/api.php?action=query&meta=siteinfo&siprop=general&format=json" | grep -o '"generator":"[^"]*"'

Output:

"generator":"MediaWiki 1.46.0"

# See the parser's HTML output for a page (the raw pipeline result, before the skin)
curl -s "https://wikibase.ronzz.org/api.php?action=parse&page=Main_Page&format=json" | grep -o "<p><strong>[^<]*"

Output:

<p><strong>Hi, welcome to ronzz.ORG's wikibase.

# Preview without saving: run a snippet of wikitext through the parser
curl -sG "https://wikibase.ronzz.org/api.php" --data-urlencode "action=parse" --data-urlencode "text='''Bold''' and ''italic''" --data-urlencode "format=json" | grep -o "<b>.*</i>"

Output:

<b>Bold</b> and <i>italic</i>

# Every edit leaves a trace: the last three revisions of Main Page
curl -s "https://wikibase.ronzz.org/api.php?action=query&prop=revisions&titles=Main_Page&rvprop=timestamp%7Cuser&rvlimit=3&format=json" | grep -oE '"user":"[^"]*"|"timestamp":"[^"]*"'

Output:

"user":"Rongzhou"
"timestamp":"2026-08-24T14:55:13Z"
"user":"Rongzhou"
"timestamp":"2026-08-21T06:08:37Z"
"user":"Rongzhou"
"timestamp":"2026-08-19T18:59:55Z"

See the preprocessor stage directly: Visit Special:ExpandTemplates

• paste {{HowItWorks}} into the input box and click "Expand" —
• you see the expanded wikitext, before the parser turns it into HTML.

Verification: the outputs above were checked against the live API on 2026-08-28:

• Siteinfo API — version, PHP and database, extension list
• Parse API for Main Page
• Parse API with raw text
• Revisions query (timestamp|user)

Further reading

• Manual:MediaWiki architecture — the canonical architecture deep-dive (also a chapter of the Architecture of Open Source Applications book)
• Manual:Contents — the technical manual of the software
• MediaWiki — the software project page
• Manual:Skins — skins documentation
• Help:Editing pages — user documentation for editing
• Help:Edit conflict — how conflicts are detected and resolved