mediawiki

MediaWiki

MediaWiki
Daniel J. Barrett
Tomcat
™
The Definitive Guide
Jason Brittain and Ian F. Darwin
Beijing
•
Cambridge
•
Farnham
•
Köln
•
Sebastopol
•
Taipei
•
Tokyo
main.title Page iii Monday, May 19, 2008 11:21 AM
MediaWiki
by Daniel J. Barrett
Copyright © 2009 Daniel J. Barrett. All rights reserved.
Printed in the United States of America.
Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol,
CA 95472.
O’Reilly books may be purchased for educational, business, or sales promotional

use. Online editions are also available for most titles (). For
more information, contact our corporate/institutional sales department: (800)
998-9938 or
Editor: Mike Loukides
Production Editor: Sumita Mukherji
Copyeditor: Emily Quill
Proofreader: Sumita Mukherji
Indexer: Daniel J. Barrett
Cover Designer: Karen Montgomery
Interior Designer: David Futato
Illustrators: Robert Romano and Lesley
Borash
Printing History:
October 2008: First Edition.
Nutshell Handbook, the Nutshell Handbook logo, and the O’Reilly logo are regis-
tered trademarks of O’Reilly Media, Inc. MediaWiki, the image of mimic butterflies,
and related trade dress are trademarks of O’Reilly Media, Inc.
Many of the designations used by manufacturers and sellers to distinguish their
products are claimed as trademarks. Where those designations appear in this book,
and O’Reilly Media, Inc. was aware of a trademark claim, the designations have
been printed in caps or initial caps.
Java™ is a trademark of Sun Microsystems, Inc.
While every precaution has been taken in the preparation of this book, the publisher
and author assume no responsibility for errors or omissions, or for damages result-
ing from the use of the information contained herein.
ISBN: 978-0-596-51979-7
[M]
1223310664
Table of Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Part I. Getting Started
1. A First Look . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
What’s MediaWiki? 4
A Typical Day on a MediaWiki Site 4
When to Use MediaWiki 5
When Not to Use MediaWiki 6
Additional Resources 7
2. Basic Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Quick Tour of a Wiki Page 9
Articles 12
Editing Primer 20
Menu Reference 23
Getting Help 27
3. Your User Identity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Creating an Account 30
Logging In and Out 30
User Pages 31
Signatures 32
Watchlists 33
Tracking Your Contributions 35
Preferences 35
User CSS and JavaScript 43
v
Part II. Writing and Editing Articles
4. Editing Articles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Getting Started with Editing 48
Creating an Article 51
Paragraphs and Headings 52
Typestyles and Fonts 54
Links (Briefly) 55

Images and Uploaded Files 56
Lists 61
Tables 68
Mathematical Formulas 70
Escaping Wikitext with <nowiki> 71
Conflicts 72
Beyond the Basics 73
5. Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Internal Links 75
External Links 81
Interwiki Links 84
Interlanguage Links 84
Graphical Links 86
File Links 86
Linking Tips 87
6. Organizing Articles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Categories 90
Namespaces 96
Subpages 99
Redirects 101
Disambiguation Pages 103
Renaming Articles 104
Deleting Articles 106
7. Advanced Article Construction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Maintaining a Consistent Wiki 108
Variables 109
Templates and Transclusion 112
Logical Parser Functions 122
Dynamic Page List 124
Recipes for Refactoring 132

vi | Table of Contents
8. Special Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Maintenance Reports 140
List of Pages 147
Login/Sign Up 149
Users and Rights 150
Recent Changes and Logs 152
Media Reports and Uploads 155
Wiki Data and Tools 157
Redirects and Random Pages 158
High-Use Pages 159
Page Tools 161
Other Special Pages 163
Special Pages Grouped by Task 165
Part III. Running and Administering MediaWiki
9. Installing MediaWiki . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Before You Begin 174
Installing the Prerequisites 176
Installing MediaWiki 180
Important Optional Features 187
A Tour of MediaWiki’s Files 193
Maintaining the Code 196
10. Practical Wiki Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Adopting MediaWiki 203
Planning 206
Establishing Standards 210
Governance 212
Integrating with Other Websites 213
11. Configuring MediaWiki: An Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Administrative Roles 216

Advanced Page Constructs 217
Special Pages for Sysops and Bureaucrats 218
System Messages 218
Cascading Stylesheets 223
JavaScript 223
Configuration Settings 224
Extensions 225
Skinning 225
Table of Contents | vii
SQL Programming 225
Maintenance Scripts 226
12. Controlling Wiki Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Users 227
User Rights and Permissions 229
Article Content 236
Configuring the Editing of Articles 238
Maintaining Articles 241
Configuring Namespaces 245
File Uploads 248
Search 250
Special Page List 252
Database Configuration 252
Email Configuration 253
JavaScript Configuration 253
Logging and Debugging 254
13. Changing Appearances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
The Basics 257
Menus 260
Search Box 265
Tables of Contents 266

External Link Appearance 266
Page Credits 266
Overall Look and Feel 267
International Support 269
14. Installing Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Obtaining Extensions 271
Installing an Extension 272
Recommended Extensions 274
15. Creating Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Overview of Extension Types 282
Creating a Variable 289
Creating a Parser Function 291
Creating a Tag Extension 294
Behavior Changes 299
Creating a Special Page 301
Useful Tasks for Extension Writers 307
Creating a Skin 313
viii | Table of Contents
Publishing an Extension 316
Other Extension Topics 316
Finding a MediaWiki Programmer 317
16. Wiki Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Maintenance Scripts 320
Backups 320
Upgrades 322
Read-Only Wiki 323
Performance and Scaling 323
Security 327
Vandalism 329
Common Maintenance Tasks 330

For More Information 333
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Table of Contents | ix

Preface
In 2001, Wikipedia changed the world by proving that thousands of strangers
could collaborate to produce a valuable information resource. Encyclopedia
publishers shuddered. Skeptics scoffed. And in the meantime, users around
the world have produced millions of Wikipedia articles.
Wikipedia was not the first wiki,
*
but it’s clearly the most successful, largely
due to its powerful software, MediaWiki.
This book is about making MediaWiki work for you, whether you plan to read
wikis, write and edit articles, or install and run your own MediaWiki site.
Who Should Read This Book?
This book serves four audiences:
Wiki readers
Anyone who reads Wikipedia or other wikis running MediaWiki software.
Wiki authors
Anyone who writes or edits wiki articles.
Wiki sysops
Authors with special privileges for maintaining the wiki.
Wiki administrators
System administrators and programmers who install, configure, and run
MediaWiki on a server.
Roadmap
Part I of this book is dedicated to wiki readers, explaining how to navigate a
MediaWiki site effectively. Part II focuses on authors, and discusses how to
*

That honor goes to WikiWikiWeb, created by Ward Cunningham in 1994.
xi
write and edit wiki articles, beginning with the basics and moving to more
complex tasks. Part III is for administrators and programmers. We’ll cover how
to install and maintain a MediaWiki site, how to configure its many settings,
and how to program your own features, called MediaWiki extensions.
Conventions Used in This Book
The following typographical conventions are used in this book:
Italic
Indicates new terms, URLs, email addresses, filenames, and file
extensions.
Constant width
Used for program listings, wiki articles, wiki categories, wiki namespaces,
as well as within paragraphs to refer to program elements such as variable
or function names, databases, data types, environment variables, state-
ments, and keywords.
Constant width bold
Shows commands or other text that should be typed literally by the user.
Constant width italic
Shows text that should be replaced with user-supplied values or with val-
ues determined by context.
This icon signifies a tip, suggestion, or general note.
This icon indicates a warning or caution.
Using Code Examples
This book is here to help you get your job done. In general, you may use the
code in this book in your programs and documentation. You do not need to
contact us for permission unless you’re reproducing a significant portion of
the code. For example, writing a program that uses several chunks of code
from this book does not require permission. Selling or distributing a CD-ROM
of examples from O’Reilly books does require permission. Answering a ques-

tion by citing this book and quoting example code does not require permission.
xii | Preface
Incorporating a significant amount of example code from this book into your
product’s documentation does require permission.
We appreciate, but do not require, attribution. An attribution usually includes
the title, author, publisher, and ISBN. For example: “MediaWiki by Daniel J.
Barrett. Copyright 2009 Daniel J. Barrett, 978-0-596-51979-7.”
If you feel your use of code examples falls outside fair use or the permission
given above, feel free to contact us at
Safari® Books Online
When you see a Safari® Books Online icon on the cover of your
favorite technology book, that means the book is available online
through the O’Reilly Network Safari Bookshelf.
Safari offers a solution that’s better than e-books. It’s a virtual library that lets
you easily search thousands of top tech books, cut and paste code samples,
download chapters, and find quick answers when you need the most accurate,
current information. Try it for free at .
How to Contact Us
Please address comments and questions concerning this book to the publisher:
O’Reilly Media, Inc.
1005 Gravenstein Highway North
Sebastopol, CA 95472
800-998-9938 (in the United States or Canada)
707-829-0515 (international or local)
707 829-0104 (fax)
We have a web page for this book, where we list errata, examples, and any
additional information. You can access this page at:
/>To comment or ask technical questions about this book, send email to:

For more information about our books, conferences, Resource Centers, and

the O’Reilly Network, see our website at:

Preface | xiii
Acknowledgments
As always, I thank O’Reilly Media and my long-time editor, Mike Loukides,
for believing in the idea of this book. I also thank members of the O’Reilly
Editorial, Production, and Tools team (Karen Crosby, Keith Fahlgren, Abby
Fox, Marlowe Shaeffer, and Adam Witwer) for their quick responses to my
DocBook typesetting questions and requests, and the illustrators and produc-
tion team for turning my manuscript and sketches into a finished product. Big
thanks to the technical review team (Shannon Bohle, Rob Church, Brion Vib-
ber, JP Vossen, and Jim R. Wilson) for their careful reading and thoughtful
suggestions that tangibly improved the book. (Of course we used a wiki to
review and discuss the manuscript.)
I’d also like to thank my colleagues at VistaPrint: Jeromy Carriere and Robert
Dulaney for permission to work on this project, Wendy Cebula for harping on
“people, process, technology,” Jim Sokoloff for Subversion tips (notably, ex-
ternals and vendor branches), Paul Shelman for inspiration, and all my col-
leagues in Capabilities Development for their many questions and requests
that propelled me up the MediaWiki learning curve. In the MediaWiki com-
munity, I thank the MediaWiki development team for creating a
world-changing tool, readers of mediawiki-l who answered my obscure ques-
tions about internals (especially Brion), and the writers of some outstanding
third-party extensions (Ilya Haykinson, Amgine, Unendlich, Cyril Dangerville,
and Gero Scholz for Dynamic Page List; Tim Starling for ParserFunctions; and
many others). Thanks also to Robert Strandh for opening my eyes to the dis-
tinction between “ease of use” and “ease of learning.”
Finally, I thank my family, Lisa and Sophia, for their amazing patience and
love.
xiv | Preface

PART I
Getting Started

CHAPTER 1
A First Look
“The whole world is singin’ this song wikki-
wikki-wikki-wikki ”
—Newcleus, “Jam On Revenge”
A wiki is a website that lets people freely create, edit, and link a collection of
articles. Now, every website can be considered a bunch of interlinked pages,
but wikis allow the content and the structure to be changed by a community.
Wikis are a great way for a group of people to coordinate and create content,
even if that group is made up of thousands of people in different places.
Here are some typical things you can do on a wiki:
• Create an article on a topic that interests you.
• Make changes to other people’s articles, without requiring their
permission.
• Create links between articles.
• Group similar articles together into convenient categories.
• View the history of an article to see all the changes, who made them, and
when.
• See interesting statistics about the articles: which ones are most popular,
which ones probably need updating, and so on.
Wikis are often devoted to a particular topic or theme. Wikipedia (http://www
.wikipedia.org) is an encyclopedia, videoville () is de-
voted to music videos, The Aquarium Wiki (aquariumwiki
.com) covers aquatic topics, and so on. Within corporate intranets, wikis serve
as documentation systems and help employees share knowledge.
3
What’s MediaWiki?

MediaWiki is the world’s most popular wiki software, and with good reason.
It’s pretty easy to use, has powerful features, is highly configurable, scales up
to millions of users, and best of all, it just plain works. More than 2,000 wikis
are powered by MediaWiki worldwide, including Wikipedia.
*
Thanks to the
generosity of its creators, MediaWiki is freely available, so anyone can create
wikis with it.
Wikipedia has some features that aren’t standard in
MediaWiki. We’ll point them out as they come up.
MediaWiki is freely distributable,
†
so you can download, install, run, and
share it without cost. It’s also open source, so any competent programmer can
modify its internal behavior (its source code) if desired.
A Typical Day on a MediaWiki Site
To give you an idea of the workings of a wiki, here’s a short story about a
nonexistent wiki and its users.
It’s a sunny day on the Web, and the hard drives are humming at BongoWiki,
a popular wiki devoted to musical instruments. Users from around the world
come to www.bongowiki.org, log in with a username and password, and create
and edit articles. At the moment, user Wackerman is creating a new article
about snare drums, and user StrataVarious is updating an older article on violin
strings.
Wackerman uses the wiki’s built-in search engine to check for an existing snare
drum article. Finding nothing, he clicks an Edit link and begins writing: not
just words, but additional symbols called wikitext that produce headings, bul-
leted lists, graphical images, and other typesetting effects. His first sentence
looks like this:
The '''snare drum''' is an essential part of a [[drum kit]].

The triple quotes mean “display this word in boldface,” and the brackets pro-
duce a link to another wiki page, drum kit. When finished, Wackerman
*
Source: />†
Under the GNU General Public License, />4 | Chapter 1: A First Look
previews his work, enters a change comment to describe what he’s done, and
saves the article. It is instantly available for other users to read.
Meanwhile, StrataVarious has browsed to an article on violin strings by fol-
lowing category links. Beginning in the Instruments category, she browses to
Stringed instruments, then Violins, then Violin parts, and finally to the ar-
ticle called Violin strings. Clicking the Edit link, she makes the necessary
changes, previews the results, enters a change comment, and saves.
Behind the scenes, a wiki sysop named Scribe is monitoring activity on the site.
She visits the Recent Changes page, notices the edits by Wackerman and
StrataVarious, and checks that they conform to the wiki’s published standards.
She fixes a broken link in the Violin strings article, enters her comment, and
saves. Then she visits the New Pages page to see what articles have appeared
today and, to her surprise, discovers that an anonymous user has created hun-
dreds of articles with nonsense names. It’s a clear case of wiki vandalism. Using
a special page on the wiki, she bans further edits from that user’s IP address.
Then she heads to a discussion area called a talk page and posts a note for
other sysops, proposing that wiki edits should be restricted to logged-in users
only. Other sysops disagree, and vigorous debate follows.
Another sysop, Conductor, reads Scribe’s note and begins deleting the bogus
articles. After several dozen, he gets tired and wishes there were a way to re-
move all the vandal’s articles in one shot. He emails a wiki administrator,
explaining the problem. Using the PHP programming language, the adminis-
trator creates and installs a MediaWiki extension that deletes all recent articles
coming from a given IP address.
‡

Conductor runs the extension and wipes out
the bogus articles instantly.
Over many months, BongoWiki grows to be the largest and most trusted re-
pository of musical instrument knowledge on the Web. And yet none of the
hundreds of authors have ever met one another in person. This is the power
of wikis.
When to Use MediaWiki
As the preceding story demonstrates, MediaWiki is a terrific collaborative tool.
It’s ideal for:
Informal knowledge-sharing
With its “anyone can edit anything” philosophy, MediaWiki works well
for building a repository of knowledge in bits and pieces. It’s far lighter-
weight than the big, commercial content management systems.
‡
There really is an extension like this: Nuke, by Brion Vibber, />When to Use MediaWiki | 5
Quick turnaround
MediaWiki is easy and rapid to use. Not all features are easy to learn, but
once you know them, you can search, modify, and maintain the content
very efficiently.
Communities of like-minded people
MediaWiki is fantastic for rapid, informal sharing of knowledge among
company employees, scientists, professors, students, and other groups.
It’s particularly great for technical communities, like software developers
or system administrators accustomed to markup languages like HTML.
Global communities
MediaWiki is built to be multilingual, supporting a range of languages and
locales.
Ease of administration
A small number of people can run a wiki fairly efficiently for large numbers
of users. Even a single capable sysop/administrator can support hundreds

of readers and authors.
Reliability
MediaWiki is stable, solid software. New releases are run for months on
Wikipedia before they’re packaged as official releases, so most bugs are
squashed by then. The software just works.
When Not to Use MediaWiki
MediaWiki software is terrific for a community of geographically distributed,
like-minded people producing an information resource. But it’s not for every
purpose. In particular, it’s not for:
Applications that need strict access control
MediaWiki is a public system at its core. Although you can restrict access
to individual articles and, to a limited extent, sets of articles, the software
is not optimized for this purpose, maintenance gets painful as the wiki
grows, and the access control methods are not necessarily secure.
General content management
MediaWiki is not a content management system (CMS). It has no work-
flow, its handling of uploaded documents is fairly primitive, it doesn’t
integrate with popular applications like Microsoft Office, and, as men-
tioned, its access control model is not very flexible.
Users with limited technical skill
MediaWiki requires its users to learn wikitext, a markup language to in-
dicate bold, italics, links, and so on, which may be a burden for nontech-
nical users. While you can create articles without wikitext—just by typing
6 | Chapter 1: A First Look
paragraphs of plain text—this doesn’t take advantage of the wiki’s power.
Nontechnical users might be happier with a wiki that has a WYSIWYG
*
editor.
Use MediaWiki for what it does best: facilitating collaboration on a massive
scale. We’ll speak more about the challenges of rolling out a MediaWiki site

to users in Chapter 10.
Additional Resources
MediaWiki is extensively documented online. Most of the material is scattered
throughout three sites: Wikipedia, MediaWiki.org, and Meta-Wiki, each or-
ganized in its own way. There are also a number of useful mailing lists. Here’s
a quick reference guide:
Wikipedia
Wikipedia’s extensive help system, />tents, documents wikitext and covers many interesting policies and pro-
cedures. These procedures are tailored to Wikipedia’s needs, but might
be applicable to other wikis as well.
MediaWiki.org
The official site documents the MediaWiki soft-
ware, third-party extensions, wiki configuration, system administration,
and much more. This is also where you download MediaWiki software
and updates.
Meta-Wiki
is devoted to all the projects of the Wikimedia
Foundation, including MediaWiki and Wikipedia. It also includes exten-
sive documentation on MediaWiki’s features, though much of it is being
migrated to MediaWiki.org.
mediawiki-l mailing list
Wiki features are discussed in several mailing lists described at http://www
.mediawiki.org/wiki/Mailing_lists. You can subscribe or simply read the
archives. The most important list for our purposes is mediawiki-l, which
discusses installing and configuring MediaWiki software; its archives are
at />*
WYSIWYG = What You See Is What You Get.
Additional Resources | 7

CHAPTER 2

Basic Use
Wikipedia and thousands of other websites run MediaWiki, and this chapter
will teach you how to get started using any of them: finding and reading arti-
cles, basic editing, and so forth. Thanks to the software’s consistent operation
and behavior, once you find your way around one MediaWiki site, you’ll feel
at home on any of them. In this chapter, we’ll introduce:
General look and feel
The common parts of a MediaWiki page
Navigation
Moving around from page to page
Articles
The main content of the wiki
Searching
Finding articles by keyword
Categories
Organizing similar articles into groups
Namespaces
Dividing the wiki into sections
We’ll also briefly discuss writing and editing articles, just enough to get you
started. Chapter 4 will cover this topic in detail.
Quick Tour of a Wiki Page
On any MediaWiki site, such as Wikipedia, you’ll see the same basic compo-
nents on each page.
*
Some parts might be stylized (or “skinned”) differently,
*
A notable exception is the wiki’s home page, which likely has an individualized layout, as in
Wikipedia’s case.
9