YK: Chapter 4: MediaWiki syntax

MediaWiki syntax

MediaWiki provides its own syntax, known as “wikitext”, for doing standard formatting like section headers, links and tables. It’s intended as a simpler alternative to HTML, and one that allows more standardization of display. MediaWiki syntax has caused a lot of angst, especially for new users, but it’s not all that difficult once you understand the basic rules. And with the addition of templates, parser functions and the like, MediaWiki gains the ability to have almost unlimited customization of the page content.

Wikitext

MediaWiki allows some HTML within wiki pages, but for the most part all formatting is done using a syntax called “wikitext”. Despite its generic name, “wikitext” refers specifically to MediaWiki’s markup language; other wiki engines’ syntax have their own names. Let’s go through the elements of wikitext.

Newlines

First, newlines: a single newline between two lines will be ignored. To make a paragraph break, you need two newlines, i.e. an empty line between the two paragraphs. More than one empty line will lead to a bigger gap.

Pre-formatting

Starting a line with one or more spaces will lead to that line being displayed in a pre-formatted way. So having a line like “ This is some text” (note that first space) is equivalent to “

This is some text

”. (

is a standard HTML tag.)

Headers

Headers are defined by putting the header text on a line by itself, surrounded by an equal number of equals signs (“=”) on both sides. The standard way to create a top-level header is by putting it between two ’==’, like this:

==Instructions==

This corresponds to the HTML tag <h2>. You can actually also use <h2>, but then the header won’t show up in the page’s table of contents, and it won’t get an “Edit” link.

Headers for sub-sections, sub-sub-sections, etc. are defined using a progressively higher number of equals signs. You can also use a single pair of equals signs, which creates an <h1> header, but this is not recommended, because only the page title at the top is supposed to have such a header. (Such headers are used, though, with the Header Tabs extension see here.)

Bold and italics

Bold and italics are defined using two and three single-quotes, respectively. They can also be combined together. The following wikitext:

Is ''that'' your '''desk''' on my '''''front lawn'''''?

...will produce this display:

Is that your desk on my front lawn?

Links

There are two kinds of links you can create: internal (to other wiki pages), and external (to outside URLs). To create an internal link, use double square brackets, like this:

[[Favorite balloons]]

You can modify the link text, by adding more text after a pipe (“|”), like this:

[[Favorite balloons|Check out my favorite balloons!]]

MediaWiki also has a feature called “link blending”, where text placed after an internal link gets incorporated into the link display. This feature is used often on Wikipedia. So if the name of the article is just “Favorite balloon”, but you still want the link to read “Favorite balloons”, you could do:

Check out my [[favorite balloon]]s!

Note also that, by default, the first letter in the link is case-insensitive.

External links are done using single square brackets, and there there’s no pipe before the link text you just put in the URL, and add the link text right afterwards. (This is because true URLs don’t contain spaces spaces, like various other special characters, get URL-encoded.) So you could have something like this:

[ http://geocities.com/joeuser/balloons.html Check out my favorite balloons from 1996!]

Lists and indentation

You can also create numbered and unnumbered lists. Here is text to create an unnumbered list, with bullet points:

These

are

some bullet points

This will produce the following text:

• These

• are

• some bullet points

You can make hierarchical bullet point lists, by using multiple asterisks together. The following wikitext:

These are

- some nested

- bullet points

...will produce this:

• These are

• some nested

• bullet points

To display a numbered list, use “#” instead of “*”. So the following text:

Buy groceries

Cook

Eat

...will produce this:

1. Buy groceries

2. Cook

3. Eat

Care has to be taken with numbered lists not to put any extra newlines between one numbered row and the next, because if that is done the numbers will start over at 1.

You can indent text, by putting “:” at the beginning of the line. As with asterisks, putting multiple colons at the beginning of the line will indent further. This comes in very handy in talk pages (see here).

Semicolons at the beginning of a line will bold the text; they’re meant to be used for definition headers. There’s an interesting bit of formatting to them that takes some getting used to putting a colon on that line splits it up into “term” and “definition”. So if you have wikitext like this:

Ray: A drop of golden sun

It will produce a display like the following:

Ray

A drop of golden sun

Tables

There is also special syntax for defining tables. Here is code for a simple table:

{| class=\textquotedblwikitable\textquotedbl

! 10:30 - 11 AM

| style=\textquotedblfont-style: italic\textquotedbl | Snack break

|-

! 11 - 11:30 AM

| Clay sculpting

|}

“{|” and “|}” mark the beginning and end of the table. “!” marks a header cell, while “|” marks a regular cell. “|-” separates between rows. And note the presence of the “class” and “style” declarations. You can add such HTML-style attributes to the main table, as well as to any individual cell. If there is also text in a cell, separate the attribute from the text with a “|”. This text will produce a table like the following:

10:30 - 11 AM Snack break

11 - 11:30 AM Clay sculpting

You can also put table cells on the same line within the wikitext, which can possibly make for easier reading. To do that, just use “||”, or “!!”, to separate the cells. For instance, the following wikitext will produce a table consisting of a single horizontal row of three cells:

{| A || B || C |}

Transclusion

You can embed pages within other pages if, for instance, you have a lot of content whose editing you want to break up into multiple pages but still display together. If you have a page like “History of chairs” that you want to embed in a page called “Chairs”, you can do that with the following wikitext:

For pages in namespaces other than the main one, you would simply put the entire page name in curly brackets, like:

Such embedding is also called “transclusion”. (You can see an explanation of namespaces here.)

The most important use of such transclusion is to include templates, which, unlike other page types, can take in variables when they’re called. Templates are covered later in this chapter.

Within transcluded pages, one can add the markup tags <noinclude>, <includeonly> and <onlyinclude>, all of which affect what shows up when the page is both viewed on its own, and transcluded elsewhere. These three tags are all covered in the section on templates.

Finally, here is a brief listing of all the main elements of MediaWiki wikitext. Some of this syntax won’t be covered until later sections and chapters, but it may be helpful to have it all in one place, for easy reference:

--------------------------------------------------------------------------------

''italics''

'''bold'''

'''''bold and italics'''''

==standard header==

===next-level header=== (...and so on)

[[Internal link]]

[[Internal link|alternate text]]

[ http://example.com text of external link]

[[Category:Example]] (category tag)

[[:Category:Example]] (link to category)

---- (horizontal line)

bulleted item

numbered item

indentation

double indentation (...and so on)

term: definition

[[ File:Image-name.jpg|thumb|frame|Caption text]]

{{Template name}} (call to template)

REDIRECT [[Page name]]

--------------------------------------------------------------------------------

This short reference is based on the Wikipedia syntax “cheat sheet”, available here:

https://commons.wikimedia.org/wiki/File:Cheatsheet-en.pdf

If you’re planning to do any substantial MediaWiki editing, and you’re just starting out, it can be helpful to print that sheet out.

Interwiki links

Interwiki links are basically a way to make external links to other wikis be callable like internal links, with two brackets instead of one. This is helpful for a few reasons: to clarify that some external wiki is a trusted source of information (and is trusted in general), to make linking to such wikis easier for editors, and to allow for linking from the sidebar.

In order to have interwiki links pointing to a particular site, you first need to define an alias for that site, based on its URL structure. For instance, if you want interwiki links to the English-language Wikipedia, you could define a link like “enwp”, which looks like the following:

http://en.wikipedia.org/wiki/$1

An interwiki link using this alias could then look like:

[[enwp:Rainbow|rainbow]]

The text “Rainbow” would get substituted into the URL, where the “$1” is so the linked URL would be http://en.wikipedia.org/wiki/Rainbow.

And since it’s a link, you can include alternate link text (as shown in the example) this is always recommended, because otherwise the interwiki alias (in this case, “enwp”) will show up in the link text.

How do you define interwiki aliases? You can do it directly in the database, by adding to the “interwiki” table, but the recommended way is to use the Interwiki extension:

https://www.mediawiki.org/wiki/Extension:Interwiki

This extension provides a nice graphical interface, at Special:Interwiki, for managing the set of interwiki aliases on a wiki.

Until 2013, interwiki links were also used in Wikipedia to define “interlanguage links”: interwiki links placed on the bottom of the page, containing a known language code as the interwiki alias, were displayed as links in the sidebar to the article’s equivalents in other languages. Interlanguage links are now defined centrally, via Wikidata. If you want to set up this capability on your wiki, though if you have a Wikipedia-style setup, with multiple wikis for the same content in different languages you can do that by adding the following to LocalSettings.php:

$wgInterwikiMagic = true;

$wgHideInterlanguageLinks = false;

Including HTML

Most HTML tags can be included in wikitext, though they’re not usually necessary. Allowed tags include <div>, <span>, <p>, <br>, table tags like <table>, <tr> and <td>, and all the header tags like <h1>, <h2>, etc. Notable tags that aren’t allowed are <a>, <img>, <script>, <form>, <fieldset>, and the structural tags like <head>, <title>, etc.

For the most part, the HTML tags that aren’t allowed are disallowed for security reasons. If there’s specific HTML that you want to include on wiki pages, but can’t because of these restrictions, the best approach to including it is to use the Widgets extension ( see here). There are other extensions that allow for embedding HTML, with varying levels of security; you can see a list here:

https://www.mediawiki.org/wiki/HTML_restriction

HTML comment tags can also be included, and that’s how comments (explanatory text that you don’t want to be displayed) are done in MediaWiki. Here’s an example:

Jhon Smith

Starting with HTML 5, browsers have supported adding “microdata” within pages, so that search engines and the like can get a better understanding of the nature of the contents like that a certain text represents a business phone number. This is done via additional HTML tag attributes like “itemtype” and “itemprop”. The best-known current schema for microdata is Schema.org. You can have the MediaWiki parser allow these attributes by just adding the following to LocalSettings.php:

$wgAllowMicrodataAttributes = true;

Templates

Templates are an integral part of the MediaWiki system. Technically, they’re nothing more than pages that can substitute in values when they’re transcluded, but that simple functionality opens up a world of possibilities. Templates are all stored in the “Template:” namespace (namespaces are described here). At their most basic, templates can simply be a piece of text. For instance, you could have a perfectly valid template called “Hello”, whose page, located at “Template:Hello”, contains just the following text:

Hello, everybody!

Once that page was created, you could put the following text anywhere in any wiki page:

Placing double curly brackets around a text makes MediaWiki look for a template with that name, and then place its contents on the page if the template is found. In this case, the call would be replaced by the text “Hello, everybody!”.

Here’s an example of a more complex template, “Needs work”, which looks more like the way templates in MediaWiki usually work. The “Needs work” template is meant to provide a simple way for users to tag pages that have problems. On the page “Template:Needs work”, we could have the following code:

This is the "Needs work" template. You can pass to it the field "Problem".

</noinclude>

<div style="border: 1px solid black;">This page needs work, for the following reasons(s): {{{Problem|}}}.</div>

</includeonly>

Let’s go through this code. The <noinclude> tag is meant to hold text that is only displayed when users look at the template page itself; it should be text that describes the template. The <includeonly> tag, on the other hand, holds text that will only be displayed on the page where the template is transcluded/called. Neither tag is necessary (though they’re both recommended); and any text not contained in either tag will be displayed both on the template page and on pages in which it’s called. Thus, the page "Template:Needs work" would display just this:

This is the "Needs work" template. You can pass to it the field "Problem".

A user, seeing a page that needed work, could add a call to the "Needs work" template to the top of such a page, so it looks like this:

A bat is a kind of bug that lives in caves. It has glowing eyes that can shoot lasers!

The page would then get displayed as:

This page needs work, for the following reasons(s): Incorrect information.

A bat is a kind of bug that lives in caves. It has glowing eyes that can shoot lasers!

The value or values passed in to the template are substituted into the corresponding parameters defined in the template’s code. Parameters are specified using three curly brackets. Why does the template contain the string "{{{Problem|}}}" and not just "{{{Problem}}}"? That’s because MediaWiki has the unfortunate default behavior of literally displaying parameter strings if values aren’t passed in to them. So, if the template contained simply "{{{Problem}}}", and the template call looked like "{{Needs work}}" (i.e., with no values), the call would get displayed as:

This page needs work, for the following reasons(s): {{{Problem}}}.

The pipe placed at the end tells MediaWiki to display an alternate string if the parameter isn’t set: in this case, nothing. You could also use the pipe to display alternate text: if the parameter tag looked like “{{{Problem|Unknown}}}", then a plain call to the "Needs work" template would display this:

This page needs work, for the following reasons(s): Unknown

Templates can also have unnamed parameters; these are defined by their index, i.e. their order in the set of parameters, starting with 1. Let’s take a simple (and rather pointless) example, a template called "Painting" whose relevant section is this:

<includeonly>{{{1|}}} is a painting by {{{2|}}}./<includeonly>

A call that looked like "{{Painting|Composition with Red, Yellow and Blue|Piet Mondrian}}" would display the following:

Composition with Red, Yellow and Blue is a painting by Piet Mondrian.

Numbered and named parameters can be combined in the same template, which can be useful in certain situations, though it’s not usually recommended. If a template is passed both named and unnamed values, then the parameters {{{1}}}, {{{2}}} etc. will get the 1st, 2nd and so on values that do not have a name assigned to them not necessarily the 1st, 2nd etc. values.

There’s one more tag that can be used in templates <onlyinclude>. This tag is a little trickier than <noinclude> and <includeonly>, because it affects text outside of the tag itself. If you add one or more <onlyinclude> tags to a template page (or to a regular page that’s transcluded), then only the text within the <onlyinclude> tags gets displayed in other pages. All other text whether or not it’s part of <noinclude> or <includeonly> tags is ignored.

Uses for templates

There are generally six main usages for templates within MediaWiki: (1) tags to highlight problems within a page, (2) infoboxes, (3) navigation boxes, (4) structural elements, (5) formatting aids and (6) templates used as formatting aids directly by various extensions.

The "Needs work" template was an example of a problem-highlighting tag. Infoboxes are well-known to readers of Wikipedia; they usually appear on the right-hand side of the page, and show important information about the page’s subject. Figure 4.1 shows one example from the English Wikipedia.

[]

Figure 4.1 An infobox from the English-language Wikipedia

Navigation boxes typically have no parameters; on Wikipedia, they’re usually found on either the bottom or the side of the page, and show a large set of links to related pages. You can see an example of it from the English Wikipedia in Figure 4.2.

[]

Figure 4.2 A navigation box from the English-language Wikipedia

Templates can also be used to display standard structural elements of a page; a common example on the English-language Wikipedia is the “Reflist” template, which is basically just a wrapper around the Cite extension’s <references> tag function, providing some additional formatting options.

Templates can be used to do inline formatting of text and images, to simplify work for editors. An example is the "Convert" template on the English Wikipedia, which lets you convert a value in a certain unit to another unit like converting pounds to kilograms. Another interesting example is the “Chess diagram” template, which can display an entire chessboard layout. There are hundreds of other such templates on Wikipedia.

Finally, there are extensions in which templates are used to format values a template name is passed to a function, which then substitutes in to that template other values that it has generated. Semantic MediaWiki is one extension that uses such a trick, with its "template" results format. We’ll talk more about that last usage in later parts of the book. And we’ll also talk quite a bit about infobox-style templates, which are a key building block for the Semantic MediaWiki system.

Parser and tag functions

Pre-defined calls within MediaWiki are all referred to as “magic words”. There are three kinds of magic words: parser and tag functions, variables, and behavior switches. We’ll get to parser and tag functions first.

Parser and tag functions are both pre-defined functions that take in a set of inputs and display a result, or otherwise perform some action. The main difference between the two is that parser functions are called by wrapping the function with curly braces, while tag functions are called using angled brackets, in the manner of HTML or XML tags.

As an example, let’s take a (fictitious) function, ’#reverse’, that takes in a string and displays its characters in reverse. If it were a parser function, a call to it could look like:

...or:

In other words, a parser function can be defined as either taking in named or unnamed parameters. If they’re unnamed parameters, they’re defined by the order in which they’re called.

If ’reverse’ were a tag function, on the other hand, a call to it could look like this:

...or this:

In all of these cases, the call would produce the string “cba” on the page.

Just as with HTML and XML tags, parameters to a tag function can be either a content string, placed between the start and end tag, or attributes placed within the tag. This means that tag functions can have only one unnamed parameter, all the rest must be named.

How are multiple parameters passed in to parser functions? They’re separated using pipes. Here is a call to a real-life parser function, #sub, that displays a substring of a string, starting at a certain location and with a certain length:

In this case, the #sub function takes the first parameter, the sentence, and returns the substring starting at character 0, with length 4. The resulting displayed string would be "This".

The values passed in to #sub, and to all other parser functions, are separated by pipes.

But what about values that actually contain pipes how can they be passed in without confusing the function? There is a standard solution to this that’s somewhat of a hack: a template called "!" is defined in the wiki, which contains simply the string "|". You could then have a call like:

{{#sub:This is{{!}}a string with a pipe.|0|4}}

When the parameters are evaluated, the "{{!}}" will change to a "|". (The result will simply be “This”, so this is a contrived example, but hopefully you get the idea.)

That brings us to the last difference between parser and tag functions, although it’s a difference that’s becoming less of an issue. For most of the history of MediaWiki, the big weakness of tag functions was that inputs passed in to them were not first parsed.

To take an example, let’s say that there are parser and tag functions named ’spacify’, that put spaces in between all the characters in a string (this is a hypothetical example there’s probably no reason why anyone would ever want such a thing). The following calls will both display the string "c b a":

{{#spacify:{{#reverse:abc}}}}

The following calls, in most cases, would fail, however:

<spacify>{{#reverse:abc}}</spacify>

That’s because the string that would be “spacified” would be the literal string ’{{#reverse:abc}}’ or ’<reverse>abc</reverse>’. In other words, tag functions don’t allow their inputs to be parsed -- a weakness that has made them unusable for many situations.

Two features of MediaWiki, though, can help to reduce this difference between tag and parser functions. The first is the #tag function, which is part of core MediaWiki. #tag lets tag functions be called as parser functions, so that their arguments can be parsed. So if only <spacify> were defined and not #spacify, you could call the following, and it would, in fact, display "c b a":

The second is that, since version 1.16 of MediaWiki, tag functions can in fact be defined so that they parse their own parameters, just as parser functions do. As of this writing, few tag functions have been defined with this behavior, but hopefully this will become more standard in the future.

Besides #tag, there are a variety of other parser functions defined in core MediaWiki. There are also a few tags. And some parser functions are called without the ’#’ character at the beginning for the most part, this is based on when that parser function was added; older functions do not have it. Here are some of the important parser functions defined in MediaWiki:

localurl, fullurl, canonicalurl variants that produce a URL based on a page name and a query string

lc, lcfirst, uc, ucfirst lower-casing and upper-casing functions

There are a variety of other pre-defined parser functions; you can see the full list here:

https://www.mediawiki.org/wiki/Help:Magic_words#Parser_functions

There are also some tag functions, including <includeonly>, <noinclude> and . <includeonly> and <noinclude> (and <onlyinclude>) were already covered here. <nowiki> is a very useful tag, that prevents MediaWiki formatting from being applied to text. For instance, to display the following on a wiki page:

The way to do italics is with ''double apostrophes''.

You could use this wikitext:

The way to do ''italics'' is with <nowiki>''double apostrophes''.

Variables

A variable is a call that simply outputs something else in its place. Like a template call, it is surrounded by two curly brackets; but its value is set directly from PHP code. The most-used variable is “{{PAGENAME}}”, which displays the name of the page. There are dozens of other variables, including variations on the page name ({{FULLPAGENAME}}), date/time information ({{CURRENTTIME}}), information about the wiki ({{SITENAME}}, {{NUMBEROFPAGES}}), and so on. The full set of variables can be found here:

https://www.mediawiki.org/wiki/Help:Magic_words#Variables

Various extensions also define their own variables. Of special note is the extension MyVariables, which defines the three additional variables {{CURRENTUSER}}, {{CURRENTUSERREALNAME}} and {{LOGO}}, and provides a framework for defining additional variables. You can find it at:

https://www.mediawiki.org/wiki/Extension:MyVariables

Behavior switches

Behavior switches are calls that don’t actually display anything, but rather tell the parser to do something, like alter the display, or store some value. Their names are usually written in all-caps and surrounded by two underscores on both sides, and they are usually placed on a page on a line by themselves. The most well-known behavior switch is “__NOTOC__”, which tells the parser not to put a table of contents on the page. Another sometimes-useful one is “__NOEDITSECTION__”, which removes the “Edit” links that show up by default for each section header.

Some behavior switches take in parameters: these are instead called in the same manner as parser functions. An examples is “DISPLAYTITLE”, which sets the display of a page’s title to be something different than its actual name. An example call would be:

Another example is “DEFAULTSORT”; see here for more information about it.

There are about 15 behavior switches altogether defined in core MediaWiki. The current full list is: __NOTOC__, __FORCETOC__, __TOC__, __NOEDITSECTION__, __NEWSECTIONLINK__, __NONEWSECTIONLINK__, __NOGALLERY__, __HIDDENCAT__, __NOCONTENTCONVERT__, __NOTITLECONVERT__, __INDEX__, __NOINDEX__ and __STATICREDIRECT__ (and there are some aliases as well). You can find explanations of all of them here:

https://www.mediawiki.org/wiki/Help:Magic_words#Behavior_switches

YK: Chapter 4: MediaWiki syntax

Navigation menu

Personal tools

Namespaces

Variants

Views

Actions

Search

Navigation

Tools