I’m reading this right now, online. I’ll be posting notes here.
Okay, here’s some stuff about the book:
- TOC doesn’t show on mobile, so that’s really annoying.
- The book it full copyright, despite being deeply ironic on that account
- The physical printing is handled by Amazon, so the printed version of this book ought be boycotted
Written by Daniel Robbins:
I am known as the creator of Gentoo Linux, and the current “Benevolent Dictator for Life” of Funtoo Linux.
I would like to thank two organizations in particular, one a nonprofit organization and one a wildly profitable company: the Wikimedia Foundation and Google. They have both been instrumental in my involvement in, and continued benefit from, MediaWiki. It happens that, over the years, both have served all the following roles: reference source, software utility provider, sponsor of development, and client. These have been two tremendously valuable organizations, to me and to hundreds of millions of others, and I could never thank them enough for their contributions.
These early sections are small and largely sentimental, no crunch to discuss. But that paragraph is a red flag for me. Granted, this edition was released in 2014, but were we all okay with Google back then? ((Hint: we were not))
The biggest change, though, in terms of impact on this book, is the introduction of the Cargo extension in 2015. Cargo is meant to be a simpler, easier-to-use alternative to Semantic MediaWiki. SMW and its many spinoff extensions took up nearly one-third of the book in its first two printings, and were to a large extent the heart of the book. I have decided to essentially replace SMW with Cargo in this book, because I believe that Cargo is the superior solution. SMW is still discussed in the book, but just in an overview. Cargo is covered in detail – though, given that it’s a more streamlined extension than SMW, it is dealt with in only around 25 pages. The chapter on “Semantic Forms” is still there, though the extension is now called Page Forms, and is now a standalone extension as opposed to one that requires the presence of SMW.
This is also the reason I’m reading this book.
“How to Succeed in Business Without Really Trying” was a 1961 Broadway musical, and a 1952 book (thanks, Wikipedia), that parodied corporate life. But the phrase could just as well serve as a description of MediaWiki’s history. MediaWiki is best known as the software that powers Wikipedia; but it is also likely the most popular application for internal, corporate wikis. And on public wikis, those wikis whose name often ends in “pedia” or starts or ends with “wiki”, MediaWiki is unquestionably #1.
I’m gonna let that speak for itself.
MediaWiki’s developers generally do take the idea of MediaWiki as a standalone application seriously, but at the same time, most (though not all) of MediaWiki’s developers see that as a secondary issue, with the primary issue remaining improving Wikipedia. So, with MediaWiki, we have the rare situation where a software application becomes extremely successful despite being, at heart, a byproduct of another project. (Though it’s not a unique situation – the bug-tracking software Bugzilla has a similar status, and there are probably others.)
Fascinating! Is Bugzilla’s mission to run… Bugzilla for Bugzilla?
But also, I’ve wondered about the intentions of MediaWiki developers: it often superficially appears to be broken down as supporting Wikipedia or a pet/pro project.
It should be noted that the MediaWiki available to companies and organizations is quite a bit more powerful than the MediaWiki in use on Wikipedia and the like, and that’s due to a number of extensions that Wikipedia and the rest do not use, most notably Cargo and Semantic MediaWiki.
Around 10 of the extensions covered here, out of over 60 mentioned in the book, were created by me, and two of them, Cargo and Page Forms, each get a chapter (or most of a chapter); so I could be accused of using this book to market my own technology. To that I would respond that this book represents my view of the best ways to use MediaWiki; I created those extensions because I thought they were features that were missing. Years of working with clients have helped to solidify my views on the most useful configurations. And, well, it’s my book – any author writing such a book is bound to favor the tools that have worked for them.
I’m reading this for Yaron Koren’s expertise.
The book is called “Working with MediaWiki”, because it’s meant for people who are trying to do real work with MediaWiki – whether it’s for their company, for an organization, for a user community, or for themselves. Wherever possible, I try to offer a pragmatic approach, and straightforward answers to the common issues that people experience.
In this chapter, we’ll start with some of the non-technical aspects of MediaWiki.
I learned a lot from the following sections, mostly inside baseball on early policies in Wikipedia. However, it surprised me how interesting and broad the history gets. So we’re gonna spend some time here. Let’s do the sections in reverse, as the last two are straightforward.
I’ve been, um, complaining about hosting MediaWiki for close to a decade, I’m sure.
Instead of setting up a new wiki on your own domain, from scratch, you may want to have your wiki hosted on an existing website dedicated to wiki hosting – such sites are usually referred to as “wiki farms”, or, as Wikipedia prefers to call them, “wiki hosting services”.
Wikifarms are have always amused me, since I can’t quite pin down what the farm represents… are the wiki instances animals? Are pages crops? Are syops… farmers?
They list a bunch of reasons to host wherever, but it is generic to apply to most sites.
The biggest MediaWiki-based wiki farm, by far, is Wikia, at wikia.com. In fact, it’s the most popular wiki farm of any kind; according to the Alexa traffic-monitoring service, it’s currently among the top 100 most popular websites in the world, and among the top 50 in the United States.
Wikia was founded in 2004 by Jimmy Wales – the co-founder of Wikipedia – as well as Angela Beesley (now Angela Beesley Starling), who was a Wikimedia Foundation board member at the time. For that reason, some people think Wikia is affiliated with Wikimedia or Wikipedia, but in fact there’s no official connection.
I didn’t know people thought that. It must have cast a strange light on Wikipedia.
The MediaWiki-based wiki farm closest to my heart is Referata, at referata.com – that’s because I created it and still run it, via WikiWorks.
These deserve a better directory.
How to choose one of these? For simple wikis, it shouldn’t really matter. But if you have the need for special features, you can try looking at the site’s “Special:Version” page, to see what version of MediaWiki it’s running, and what extensions it has installed. You can also look at any of the wikis already hosted on that farm (usually there are a few linked from the homepage), to see what they look like, whether they’re inundated with spam (you can check Special:RecentChanges for that), how quickly they load, whether they have a distracting amount of ads, etc.
Solid hacking tips: MediaWiki loves to tell you how it works, if you know where to look.
Special:Version is the best!
Community and support
The best ways to get support are the mailing list, the IRC channel, and on the MediaWiki website at mediawiki.org.
Good to know. I wonder if there are wikae/MediaWiki jabber conferences around.
And for any specific extension, you can use its talk page on mediawiki.org to get support.
Good tip, but also something I’ve been thinking about recently: “talk pages” as semi-automated directories of networked communications. Think of the ways we use talkgroup, and how I could just load tagged threads into a talk page, based on metadata from the article it discusses. As wiki work is knowledge organizing, it doesn’t lend itself to human communications, which is messy, ad-hoc, just-in-time, etc. Discourse provides tools to split apart and glue together conversations. I think this level of separation is what the web was made for.
For Wikimedia projects and developers there are usually one or two MediaWiki-focused “summits” and “hackathons” each year, and there is also Wikimania, an annual conference on everything Wikimedia-related, which also includes a several-day hackathon. For enterprise users, there are EMWCon, the Enterprise MediaWiki Conference, which is held in the spring in the United States; and SMWCon, the Semantic MediaWiki Conference, which is held in the fall in Europe. (EMWCon began as an offshoot of SMWCon, but has a more general focus.)
Lots of events to look up. I generally ignore all of these; there is no way I can afford the entry to the “enterprise” events, and I couldn’t justify travel expenses to Wikimania as I don’t know what it is. Like, I don’t have a sense of it. It’s probably good, but am I the type it is for? Who knows?
If you think you’ve found a bug in MediaWiki or one of its extensions, or you’ve created a software patch and want to submit it, the best way to do that is at the MediaWiki bug tracker/task manager (which uses the software Phabricator), here:
This is often the best place to make feature requests as well.
My favorite Phabricator instance after the meta-instance for the Phabricator project!
The most definitive list of both individuals and companies doing MediaWiki consulting is here:
I have not looked at that. I wonder if I should add myself?! I’ve always offered wiki services, but never thought to advertise as such; folks rarely commit to a wiki. But who knows! Odder things have happened.
History of MediaWiki
Okay, this section just has so many neat parts! You should just read it, but I’m gonna quote a bunch of things I want to connect later.
In 1995 Ward Cunningham, a programmer who was already known for his work in defining software design patterns, created the first wiki, on his company’s website, c2.com.
The wiki was meant to hold information about design patterns, as part of a section on the website called the “Portland Pattern Repository”.
Cunningham was inspired by HyperCard
“Wiki” or “wiki wiki” means “fast” or “hurry up” in Hawaiian; and in fact it apparently derives from the English word “quickly”, so its new presence in English is somewhat of a return.
I knew about the Hawaiian shuttle, but I didn’t know there was more to it.
In 2000, Jimmy Wales, an internet entrepreneur living in Florida, decided to create Nupedia, a free online encyclopedia that would compete with the various subscription-only encyclopedias like Encyclopedia Britannica. He hired Larry Sanger to edit it.
Stuff happens, and…
Wales and Sanger later had a falling-out over philosophical differences, and now Sanger has become one of Wikipedia’s most vocal critics.
I looked up Sanger and read some of their stuff. I’ve always had a bitter-sweet relationship with NPOV, and Sanger is the the instigator, but e also teaches epistemology, so now I need to deep dive and make sense of this.
The software that Wales and Sanger originally ran Wikipedia on was UseModWiki, a Perl application written by Clifford Adams. UseModWiki, like most wiki software at the time, was the work of tinkerers: it was based on AtisWiki, which was based on CvWiki, which in turn was based on WikiWikiWeb, Cunningham’s original application.
Some projects to look up.
And again like most wiki software of the time, UseModWiki used flat text files to store all page revisions. That approach was slow, and, given Wikipedia’s constant growth, was proving unworkable. Wikipedia also needed functionality that UseModWiki didn’t provide, so in late 2001 Wales hired Magnus Manske, a German programmer and active Nupedia contributor, to rewrite the software in PHP, now storing edits in a MySQL database.
This tickles me, since so many wikae projects use flat files. But it is an interesting point, sometimes you need a relational database. And Wikipedia, what a weird (menagerie of) beast(s).
The name “Wikimedia” was based on “Wikipedia”, and had been suggested by Sheldon Rampton on a Wikipedia mailing list in March. The next month, Wikipedia enthusiast Daniel Mayer, writing on that same mailing list, suggested a name for Crocker’s “phase III” software: “MediaWiki”, a play on “Wikimedia”. The name stuck, and was quickly made official.
I’ll give Mayer benefit of the doubt, and presume e leads a decent life void of harming others, and even then I still hate em a little bit. Just not as much as everyone on that mailing list that agreed…
They include, besides MediaWiki, the open-source applications PmWiki, Tiki and TWiki (an exception, since it was started in 1998), and the proprietary applications Confluence and Socialtext. There are also various content-management systems that include some limited wiki functionality; these include Traction TeamPage and Microsoft SharePoint.
More things to reference.
As for the Wikimedia Foundation, it has remained in charge of Wikipedia and its related sites, as well as MediaWiki. It moved to San Francisco, California in 2007, and has grown every year since 2003; it currently has almost 300 employees.
We even have some WMF employees in these here fora!
This growth has been accompanied by some conflict.
Dun dun DUN!
Things came to a head in 2016 with the resignation of Lila Tretikov, who had been the WMF’s second Executive Director.
Tretikov brought a more top-down approach to management than the Wikimedia movement had seen before, culminating in an episode in which she let a rogue high-level employee put together a secret plan for Wikipedia to compete with Google as a global search engine. How much input she had into the plan is unknown, and the plan was quickly abandoned in any case; but after it became public knowledge, she continued to deny that it had ever existed – something that might be more forgivable from a tech CEO than from a community leader. This and other issues led to a drumbeat of complaints that ended with her resignation.
Wow… granted, during the timeline I was quite busy with life, but I ran into Tretikov one day (e was nice and all, of course, approached me to welcome at an event), and then a short while later was not there. I had no idea of the stuff that happened.
And wow, “a rogue high-level employee”, such drama! The thing that I find interesting, the search engine was called Knowledge Engine. I found out about this controversy a couple months ago searching for that term, independently! I was going to call my MediaWiki that, but now I don’t want to be associated with that project…
I find this hilarious!
And this is relevant to us because among the ideas discussed in the wake of Tretikov’s resignation was that the development of MediaWiki and related software should be spun off into its own organization, perhaps to be called the “MediaWiki Foundation”, in the manner of many other organizations that manage the development of open-source software. At the time of writing in 2016, this remains an ongoing discussion, though the odds do seem stacked against it due to institutional inertia if nothing else.
Look that up.
Two names stand out, though, for the scope of their involvement. The first is Brion Vibber, who is currently the Lead Software Architect for the Wikimedia Foundation, and who has essentially had that role in MediaWiki since nearly the beginning, adding enormous amounts of code and serving as the final word on what gets into the software and onto Wikimedia sites.
The second name is Tim Starling, who serves as the WMF’s Lead Platform Architect, and who like Brion has been involved in development since nearly the beginning, has contributed a huge amount of code, and has had significant influence on the current state of the software.
Setting up MediaWiki
By far the most popular setup for MediaWiki is what’s known as the “LAMP stack”: Linux, Apache, MySQL and PHP. Only the last of these is required, but the other three are encouraged. Users have also had success with Nginx instead of Apache, in what is known as a “LEMP stack”; it seems to handle large amounts of web traffic better.
MediaWiki is fairly versatile, tech stack wise.
- Web servers: basically all of them. Anything that can handle PHP.
- Databases: MySQL/MariaDB, PostgresSQL, SQLite
From the compatibility page:
Running MediaWiki on anything other than MySQL or MariaDB is not recommended for production use at this point.
I’d love to run little MW instances on SQLite, but a lot of extentions make use of features SQLite doesn’t have, and MW may not be engineered to have little stashed instances…
For downloading there are two options put forward: git or tarball. Tarball comes with the following bundled extensions:
Cite CiteThisPage ConfirmEdit Gadgets ImageMap InputBox Interwiki LocalisationUpdate Nuke ParserFunctions PdfHandler Poem Renameuser SpamBlacklist SyntaxHighlight TitleBlacklist WikiEditor
I recognize a bunch of them. What is
Poem? Also, making a note that
Gadgets encourages picking up snippets from a wiki that is closed off to non-registered users, for some reason that isn’t clear. Potential to fix that.
Installing means downloading, and normally following the installation wizard in a web browser that then produces the
LocalSettings.php for uploading to the server.
MediaWiki wikis do have a default logo, which is a grayed-out MediaWiki sunflower logo with the words “Set $wgLogo to the URL path to your own logo image” over it. As the instructions say, all you need to do is set a new value for $wgLogo in your LocalSettings.php file.
I think logos are stupid and themes for users should have options to run without a logo.
By default, MediaWiki URLs appear in a format like:
However, the preferred format is something more like:
I hate URLs in Mediawiki.
We’ll just note that there are some cases when users want to have a URL structure that looks simply like:
It’s certainly a clean-looking URL, but this is not recommended, because, among other reasons, it means that your server can’t have helper files like robots.txt and favicon.ico.
This is a flaw in the software, and shows that Mediawiki is created for Wikipedia, and decisions about how language is constructed in a wiki URL was determined by a bunch of English speakers in the late 90s/early 2000s, and we can never change it again.
Care about URLs? Use Dokuwiki.
There’s a section on updating. It comes down to:
- Updating the codes
That last step I added, because let’s be real.
Over 1,500 publicly-released extensions exist in some form currently; though many of these are obsolete or redundant, and many never fully worked in the first place, so the number of extensions that could conceivably be used at any one time is probably closer to several hundred.
Almost all MediaWiki installations include at least a few extensions; Wikipedia uses dozens of them.
English WP uses a lot: Version - Wikipedia
The core MediaWiki code is structured in a way that makes it easy to install extensions, and develop them: the key element is the widespread use of hooks. Hooks are lines in the code that outside functions can register themselves to be called at.
Where to find them?
The site mediawiki.org is the main resource for finding out about extensions. Every extension is meant to have a page there, so you can do text searches to find specific functionality you’re looking for. You can also use the “Extension Matrix”, which is actually a collection of pages, which hold different views of the full collection of extensions:
There’s paragraphs here, so: read each extension README. If it doesn’t have install instructions, add them or ask someone else to.
Notable packages of extensions include:
BlueSpice (https://www.mediawiki.org/wiki/BlueSpice) semantic::apps (https://www.semantic-apps.com/en/Main_Page)
Besides downloading packages, you can also usually download extensions directly. One easy way to download extensions is via the “Extension Distributor”:
It’s a page on mediawiki.org that creates a downloadable file on the fly, for any extension that’s in the MediaWiki Git repository, and any applicable version of MediaWiki. However, for most extensions, these files represent a random snapshot that may not actually hold a working set of code (for instance, if someone made some bad change to the code right before the snapshot was made).
More things to look up.
Okay, that was a short chapter!
Editing in MediaWiki
This chapter starts with “tabs”, because Mediawiki is a web app, and don’t you forget it.
Creating and editing pages
In MediaWiki, every page’s URL is also its title; there are no URLs that simply look like “?id=123456”, of the type that appear in many other content-management systems. That’s important, because it means that the creation and renaming of pages can be done in a transparent way, open to all users.
What? Why and how?
A link to a nonexistent page is usually called a “red link”. By default, they’re red, which easily distinguishes them from links to pages that exist, which are usually blue. The actual MediaWiki term for them, for what it’s worth, is “broken link” (though “redlink” is also used, in URLs).
Humans constantly have trouble with color.
My favorite result of “redlinks” as a shorthand is Wikipedia:WikiProject Women in Red - Wikipedia
By default, page names always start with an uppercase letter: if a page name gets typed in that starts with a lowercase letter, it will simply get capitalized by the system. This can be changed, however, by adding the following to LocalSettings.php:
$wgCapitalLinks = false;
Set this to false to avoid forcing the first letter of page titles (including included pages, images and categories) to capitals. WARNING: may break links! This makes links COMPLETELY case-sensitive. Links appearing with a capital at the beginning of a sentence will not go to the same place as links in the middle of a sentence using a lowercase initial; typically the former has to become a link with a separate display title (e.g. [[Page|page]]).
I wonder if this ever becomes an issue for folks. For a database wiki, it is a non-issue, if one is using Page Forms to drive content updates.
Back to the book:
Page names are restricted to 255 bytes, which, depending on the character set being used, can be as many as 255 characters or as few as 63 characters. Standard Latin characters are one byte each, while most other languages’ characters are represented using two or three bytes, and some archaic languages, mathematical symbols, etc. take four bytes.
Interesting, but maybe a non-issue. Those are long URLs.
The edit page consists of, essentially, one big text area, plus some helper inputs at the bottom, including, most notably, the “Save page” button. The text of the page, or section, being edited goes in the big text area; it’s meant to be written in a syntax called wikitext, which is simpler than HTML but which can also include a lot of scripting-like functionality
You can also use an extension called WikiEditor, which provides a nicer toolbar, with support for special characters (symbols, and non-Latin characters), and other features.
The VisualEditor extension is an ongoing project by the Wikimedia Foundation to create a built-in WYSIWYG/WYSIWYM solution within MediaWiki.
The VisualEditor extension relies on the separate nodeJS-based Parsoid parser service that needs to be installed and enabled in order to edit pages with it.
The book touches on this, optimistically:
VisualEditor at this point has significant and growing use outside of the Wikimedia sites. Its performance and usability have improved substantially, and it is in stable use in a variety of wikis. The setup of the extension is a little tricky (it requires, among other things, having Node.js running on the server), but once it’s installed it seems to work well wherever it has been used.
Hmmm, I don’t like it. So imagine how surprised I was to read on Parsoid - MediaWiki
You can reach it by adding “action=history” to a page’s URL query string, and, as with the edit page, it’s available in most skins via a tab, and in some skins as a sidebar link. In English, the tab is called “History” or “View history”, depending on the skin.
One more interesting bit:
The history page doesn’t usually get much attention, although it is, in a sense, the heart of MediaWiki, because being able to see the page history is what lets wikis function like wikis.
Is that because it isn’t really needed until it is, and when it is, everything else is cruft?
Explains a diff page.