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.

MediaWiki, a wiki engine

A Wiki engine powers a wiki: a website hosting static pages, usually informative, which contributors can edit within their browser, with every change tracked and reversible. 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 is one of the most well-known wiki engines. Originally built as a summer project by early Wikipedia contributor Magnus Manske in 2001 to support a growing Wikipedia,, Mediawiki went through multiple full/partial rewrites to become what it is today.

A short history

The history of MediaWiki was intertwined with that of Wikipedia.

When Wikipedia launched in January 2001, it ran on UseModWiki, an existing wiki engine written in Perl that stored every page as a text file. This worked fine for Wikipedia's scale at the time: an ambitious but still niche startup project that no one knew if it would ever take off.

To many people's surprise, Wikipedia became an instant hit. In a few months of time, flat-file storage became a performance bottleneck. To improve performance, Magnus Manske, then a university student studying biochemistry, started building a dedicated engine in his free time over the summer of 2001: a database-driven application written in PHP, backed by MySQL. It was the first iteration of what would become MediaWiki, introducing core features still in use today: custom namespaces with dedicated talk pages, skins, and special pages. The community referred to it simply as "the PHP script".

In January 2002, the English Wikipedia switched officially to Magnus's PHP script, and the script became known as "Wikipedia phase II".

As Wikipedia continued to grow at an astronomical pace, performance problems returned in a few months. In 2002, Lee Daniel Crocker rewrote the engine again, calling the new software "Phase III". As he later described it, there "wasn't much time to sit down and properly architect and develop a solution", so he "just reorganised the existing architecture for better performance and hacked all the code". Deployed to the English Wikipedia in July 2002, Phase III added a file upload system, side-by-side diffs, and interwiki links.

In June 2003, Wikimedia Foundation was created under the leadership of Jimmy Wales. As a non-profit organisation, it manages Wikipedia's infrastructure and day-to-day operations. In July, MediaWiki, a wordplay by Daniel Mayer on the Foundation's name., was officially adopted as the name for the software behind Wikipedia. The first release under the new name followed in August 2003.

A new volunteer developer brought in a new killer feature: Tim Starling added templates to MediaWiki 1.2 (2004), allowing popular elements to be defined once and used on an infinite number of pages. Version 1.3 (August 2004) then expanded them with parameters, moved them into a dedicated Template namespace, and introduced the MonoBook skin as the new default layout.

Development has continued continuously ever since: the template preprocessor was rewritten in MediaWiki 1.12 (2008); the ResourceLoader arrived in MediaWiki 1.17 (2011);; the visual editor arrived in 2012; Parsoid, the second-generation parser originally written in Javascript to support the visual editor, was ported to PHP in 2019, with plan to become the default parser for the entire system — the "unified parser" — in version 1.47, scheduled for November 2026.

Today, MediaWiki as a free software developed in the open by its own community, powers tens of thousands of wikis, private and public, including Wikipedia, Wikidata and this very site.

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, Storing content as wikitext inflicts no performance overhead on repeated read as rendered HTML is cached on first read, ensuring that the content is parsed only 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.

# 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.

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