Wikitext as document markup

When you think of “document markup,” you might come up with HTML, CSS, Markdown, or DITA. But there’s another kind of document markup out there: Wikitext.

We have a wiki in our team that we use to share documentation with one another. A wiki is a great way to create small, standalone, but interconnected pieces of documentation. This might include examples such as a technical description about a thing, which can stand on its own, but can also link to another page to expand a particular definition of a term or phrase. That’s how wikis do: each page is self contained, but part of an overall body of other, related documentation.

When you edit a wiki page, at least with MediaWiki, you can use the editor to write and format everything. But I find it’s often easier to just learn the most common formatting that I need to do in Wikitext, the formatting system used in MediaWiki, and write pages that way. This is what the editor looks like when using Wikitext:

Here are the wiki formatting that I use most of the time:

Paragraphs

Writing paragraphs of text is really easy in MediaWiki - you just type. Just like HTML and Markdown and every other document markup, Wikitext doesn’t really care about line breaks. It collects words and fills paragraphs until it reaches a blank line. The blank line starts a new paragraph.

Headings and subheadings

MediaWiki uses very simple formatting to indicate where you need to insert a heading or subheading. Most of the time, we insert subheadings, like a second-level heading. The top-level heading is usually reserved for the page title itself.

To create a wiki top-level heading, use a single = (equals) on either side of your heading, like this:

= This is the article title =

Add a second-level heading by using two equals signs on either side, like this:

== A subsection title ==

And so on for other levels of subheadings. You can go down to six levels of subheadings with ====== but if you need more than one or two levels of subheadings, you’re probably dividing your content too finely and should consider restructuring your wiki article.

Bold and italic text

We use bold text to highlight key terms that don’t have their own page in the wiki, and italic text for other things like special “one off” terms, idiomatic text, and titles of journals or books. To format text as italic, use '' (two apostrophes) around the text. To write text in bold, use three apostrophes:

Wikitext can format text
as '''bold''' and ''italic''.

It’s very rare that we need to use both bold and italic text (and in fact, our team style guide recommends against that) but Wikitext formatting can do it anyway.

Our team doesn't do it, but you can use
both '''''bold and italic text'''''
with five apostrophes.

You can remember the bold and italic formatting this way: bold is always three apostrophes, italic is always two apostrophes, so bold plus italic is five apostrophes (3 + 2 = 5).

Links to other pages

A key to creating interconnected pages in a wiki is to link between different topics. This is very easy to do in Wikitext: surround your link with [[ and ]] and the wiki will turn that into a link, like this:

'''DITA''' is one kind of [[XML]] markup,
based on topic files including DITA [[Concept]],
DITA [[Task]] and DITA [[Reference]].

In this example, the wiki will link to a page titled XML, and other pages titled Concept, Task and Reference.

But if you need to use a different name, you can add a “vertical bar” character to separate the page link from the link title:

'''DITA''' is one kind of [[XML]] markup,
based on [[Topic|topic files]] including DITA [[Concept]],
DITA [[Task]] and DITA [[Reference]].

In this case, the wiki will link to a page called Topic but use “topic files” as the link text. Our team prefers that the link should be the same as the wiki topic, so we would likely write the content this way instead:

'''DITA''' is one kind of [[XML]] markup,
based on [[Topic]] files including DITA [[Concept]],
DITA [[Task]] and DITA [[Reference]].

Wiki pages sometimes need to link to outside pages, and Wikitext can do that too. Just like links to wiki topics, the general format is “place you’re linking to, then the link name” but it uses a single [ and ] around the link, and separates the link text from the URL with a space instead of a vertical bar character.

Download the latest version from the
[https://www.dita-ot.org/ DITA Open Toolkit] website.

Text formatting in wiki pages

Wikitext can do more formatting than this, but these are the formatting that I use most frequently when writing pages in our wiki. For more details, refer to the Help:Wikitext page on Wikipedia.