Skip to main content

Wiki Formatting And Syntax

Overview

Adding content to a wiki is straight forward—it just requires a basic knowledge of wiki syntax. So, what is wiki syntax? It's a simple set of commands that format your wiki. Don't panic. You don't need to be a computer expert to use it. With a little practice, wiki syntax becomes second nature.

Below is a list of some of the basic commands you'll need to know in order to write a wiki of your very own.

Dynamic Lists

Usable in: Category Pages, Item Pages, and Wikis.

Before we delve into creating dynamic lists, you must first understand what they are and how they function. A dynamic list is essentially an incomplete list; and because it's incomplete, you can keep adding items onto it. A dynamic list searches through material on the site looking for tags that are relevant to the list. It then groups all of the documents together in list form.

For example, let's say you've created guides of varying difficulty levels, but you want to display all the easy guides together on a category page. You can do that with a dynamic list. Simply add a tag on the guide's editing page. Type "easy" into the guide field and click add. Once all the related guides are tagged with the same identifying tag, you can create dynamic lists of step-by-step guides on any wiki page, like a category page.

You can add a title to both wikilists and guidelists by adding |title=Title of List to the tag.

You'll need the following information to create a dynamic list:

  • Tag
  • Item
  • Guide type

Use the example code below to create your own dynamic list. Simply insert your own information into the appropriate fields:

[guidelist|tag=easy|type=howto]       
[guidelist|item=iPhone 3GS|type=howto|title=iPhone 3GS Guides]

You can also create lists of wiki pages. Just add a comma-separated list of tags after the vertical bar, as in the following examples:

[wikilist|robotics]
[wikilist|robotics,technique]
[wikilist|robotics|namespace=Item]
[wikilist|robotics|title=Robotics]

You can see Dynamic Lists in action on our demo site Gunner Automotive.

Note: Wikis and guides must be public to show up in their respective lists.

Escaping Wiki Formatting

Usable in: Category Pages, Guides, Item Pages, and Wikis.

There are times when wiki syntax can get in the way of your explanations. It might happen when you are explaining code or if your particular text stylings include characters that our formatting interprets as a wiki syntax command.

Don't start pulling our your hair out just yet. You can escape wiki formatting. When you do, whatever you type into your editing page will appear "as is" on your wiki page. There are two primary methods for escaping wiki formatting: raw and code.

Raw

In all likelihood, you'll rarely need [raw], but we like to prepare you for just about everything. [raw] is typically used to include text that would normally be treated as special wiki formatting.

So, let's say that you (for some ungodly reason) want to wrap a word or phrase in two plus signs: ++insert reason here++ . Normally, wiki formatting would translate those double plus signs as a command to underline the word. [raw] prevents the wiki from making those changes.

To use it, just wrap text with a [raw] tag, like so: [raw] "your text goes here" [/raw]. Now, your text won't be interpreted as part of any wiki markup.

As a note, [raw]text doesn't take on a monospace typeface, as it does in code formatting (explained below). The purpose of [raw] is merely to escape wiki formatting. Monospace formatted text looks cool, but technically does not escape wiki formatting. If you'd prefer monospace text to [raw], just wrap your text in backquotes in the following manner: ``...``.

Code

Note: The Code escape formatting syntax cannot be used on guide steps.

You'll probably rely on [code] more frequently. Using[code]leaves your text untouched by wiki formatting, but it also displays text as monospace within a discrete block—that makes [code] especially useful for examples of actual code. Still, [code] has many different applications. We've used [code]throughout this page to enclose examples of wiki syntax in blocks.

To use [code], simply enclose your text in [code]...[/code]. Below is an example of how to add those tags:

[code]
At its heart, Automotive Right to Repair is about consumer choice. As an owner, you should have the right to repair your car wherever you want: at the manufacturer repair center, at the trusty corner mechanic, or in your driveway.
[/code]

Comments

If you ever find the need to leave notes for your fellow editors, you can easily do so with the [comment] tag. For example:

Text that will be rendered
== Header that will be rendered ==

[comment]This is a note to my fellow editors, this will not be rendered on the page.[/comment]

Anything within the comment tags will not appear on rendered wikis, but will still appear on Edit pages.

Font Styles

Usable in: Category Pages, Guides, Item Pages, and Wikis.

Plain text ain't good enough for you? Here's a cheat sheet of the wiki syntax you'll need to create different font styles:

* ''Italic''
* '''Bold'''
* '''''Super bold'''''
* ``monospace``
* x^^2^^ (superscript)
* H,,2,,O (subscript)
* ~~Strike-through~~
* ++Underlined++

Here's what the wiki syntax translates to:

  • Italic
  • Bold
  • Super bold
  • monospace
  • x2 (superscript)
  • H2O (subscript)
  • Strike-through
  • Underlined

These styles should really only be used on plain text, not newlines. It's okay to put them around things like links, but only if it's necessary. These styles are not intended to be used within link tags on the custom link text.

Headings

Usable in: Category Pages, Item Pages, and Wikis.

Headings for sections and sub-sections are the structure of a wiki. Create headings and sub-sections by wrapping a line of text in two or more equal signs (=). You can make any sub-section up to six levels deep—that's six matching pairs of equal signs around a single sub-section.

When you add sub-sections, each pair of matching equal signs makes the heading smaller. The more matching pairs you add to a sub-section, the less significant the sub-section becomes. As a note, you can't wrap a section with a single pair of equal signs (like this: =generic heading=), because that heading is reserved for the title of the entire page. Consider the title of the page as the first "section" of the article.

It's sounds complicated, but it's not. This example shows how wrapping equal signs around headings and sub-headings structures a wiki article:

A wiki on something generic
== A heading ==
=== A sub-section heading ===
==== A sub-sub-section heading ====
===== And so on... =====
== A new heading ==

After you structure your headings and sub-headings, just add text, images, and videos under the appropriate sections.

Images

Usable in: Category Pages, Item Pages, and Wikis.

Images can be clearer, quicker, and easier to use than just text. You can add images to both Answers posts and wiki articles. Use your Media Manager to upload images to use on your pages. When an image is added to the page, it will appear as a basic image tag.

You can use wiki syntax to alter many aspects of how pictures are displayed. To add more than one formatting element to a picture, simply add a pipe | between them.

Basic Image Tag

To use wiki syntax to alter images, begin with the image tag.

[image|imageid]

In this tag, “imageid” is the number that our system assigns to an image when you upload it into the Media Manager.

This image tag is the only part of the wiki syntax required to make the image display. Any additional wiki syntax is used only to modify how the image is displayed.

Image Alignment

You can use wiki syntax to change the alignment of an image on the page. If you do not specify an alignment the image will automatically align to the right.

For example, to make a picture show up in the center of a wiki article, you would use the code:

[image|125525|align=center]

It would then appear as below:

Block Image

It is also possible to align images side by side in such a way that they form a chart. You would use this code:

{table

| [image|125525|size=small]

| [image|125525|size=small]

|--

| [image|125525|size=small]

| [image|125525|size=small]

}

It would then appear as below:

Block Image
Block Image
Block Image
Block Image

Image Size

You can use wiki syntax to alter the size of an image.

The available image sizes are:

  • Small
  • Medium
  • Large
  • Original

If you do not specify the size of the image, it will go to the default size.

For example, here is the code for a picture that is medium sized:

[image|125525|size=medium]

Image Captions

Wiki syntax can be used to create a caption field below an image.

You can add captions to your images using the following wiki syntax:

[image|125525|caption=This is an example]

You can make images link to an internal or external site using the wiki syntax:

[image|125525|link=www.example.com]

If you would like to open image in a new window, use the following wiki syntax:

[image|125525|link=www.example.com|new_window=true]

The following wiki syntax includes all of the possible syntax that you can use to modify an image:

[image|<id>|size={small,medium,large,original}|align={left,right,center}|caption=<text>|link=<url>]

Videos

Usable in: Category Pages, Guides (Only in the Introduction field), Item Pages, and Wikis.

Currently, we support embedded videos from Vimeo, YouTube, and Screencast.

The only thing better than pictures are moving pictures. You can add videos to your wikis and guides to make the most of your visual documentation.

Basic Video Tag

The format for videos is similar to that for images; but rather than identifying videos by a numeric identifier specific to your site, you identify them by a link to the video on the service where the video is hosted (e.g. Vimeo).

[video|< link to video >]

Video Size & Alignment

As with images, the size and align specifications are optional, but for videos they default to large and center respectively.

[video|< link to video >|size=small
[video|< link to video >|align=left]
[video|< link to video >|size=small|align=left]

Screencast Embedding

You'll need to do a little extra work to embed videos from Screencast. You can't just copy and paste the URL for a Screencast video, because the URL to view a video on the Screencast site is very different from the URL to embed the same video. The URL you need is the last one in the big block of text you'll get if you copy and paste the Embed on your page HTML. It should look something like:

http://www.screencast.com/users/.../<long identifier>/embed

Copy that URL and paste it as the appropriate field of the wiki syntax below:

[video|http://www.screencast.com/users/.../<long identifier>/embed]

Usable in: Category Pages, Guides, Item Pages, and Wikis.

Want to add a link to your wiki? Links are automatically created for things that look like URLs. You must, however, begin that URL with (http://, https://, ftp://, etc.). Here's an example:

http://www.ifixit.com

That bit of wiki syntax gets translated to http://www.ifixit.com. If you want your own text to appear in place of a full web address, then you'll need to get a bit more complex. Just add a vertical bar after the web address and then insert the title you'd prefer for the link. Take a look at the wiki syntax below:

[http://www.ifixit.com|iFixit]

On a wiki, it becomes iFixit.

If you would like your newly created link to open in a new tab or window, just add the following wiki syntax to your link:

[http://www.ifixit.com|iFixit|new_window=true]

If you need a mailto link to a specific email address, you can use the mailto wiki syntax. Mailto links will open with your computer's default email client.

[mailto|email@example.com]

Usable in: Category Pages, Guides, Item Pages, and Wikis.

Adding a link to one of your guides is easy. Guide links automatically add in the title of the guide that they link to. Or, if you like you can specify the text that shows up for the link. You just need to identify the specific guide that you want. To do so, locate the numeric code on the guide page's URL; this number is called the numeric identifier. For example, in the URL below the numeric identifier for the guide is 132. The identifier will always be near the end of the URL, right after the guide title.

http://www.ifixit.com/Guide/Repair/Installing-iBook-G3-12-Inch-Display/132/1

Here's an example of how you could use a guide link:

* [guide|132]
* [guide|132|So you broke your display...]

This syntax yields:

In many places, you can just use a plain link to the guide page, and it'll be converted into a guide link for you.

Linking to a Step

Within a category, wiki, item page, or guide you can link directly to a step. Begin by locating the step ID of the step you would like to link to.

Once you know the step ID you can link to individual steps. Simply copy the guide URL with the step number included at the end and create a link as you normally would.

Here is an example of a link with a step ID:

http://www.dozuki.com/Guide/How+to+Locate+the+Step+ID/6427#s27794

Alternatively, you can use wiki syntax to link to an individual step.

[guide|6463|Your link text|stepid=212]

In the syntax above the number displayed after the word guide is the guideID. View guide about how to locate the guide ID.

This section only applies to iFixit.com

Product links work very similarly to guide links; they link to products in a more meaningful way than a bare URL. Like guide links, product links use the product's current title as the link text by default, but the link text can also be customized. To link to a specific product, find its product code, which is on the product page. As with guide links, you can just use a bare link to a product page and it'll be converted into a product link for you.

For example:

* [product|IF145-002]
* [product|IF145-002|If you buy one tool...]

That wiki syntax translates into the following:

Usable in: Category Pages, Item Pages, and Wikis.

Let's say you'd like to add a link to an internal wiki page, instead of an outside site. Wiki links look and behave very similarly to normal links, but are enclosed in double square brackets. As before, you have the option of supplying your own link name (as seen in the second example) :

* [[Help:Wiki Syntax]]
* [[Help:Wiki Syntax|A link to this article]]

This yields the following:

The link is given by the article's name with an optional namespace on the front, separated by a colon. If no namespace is supplied, then the default namespace is used. The square brackets and vertical bar are a common pattern you'll see applied throughout our wiki syntax.

You can also generate links to multiple wiki articles at once using the wikilist tag and then listing all the categories of articles you'd like to include, separated by a comma. A given article must match all of the listed tags in order to be displayed. Assuming you pick tags that actually match some articles, you'll get a tabular layout of article links, each link consisting of a thumbnail image and the article title. You can also narrow the search beyond the tags, to a particular namespace. You might use the tag like this:

== Articles about Category X ==

[wikilist|category-x]

== Category X articles that are also about Category Y ==

[wikilist|category-x,category-y]

== A list of Category X articles titled as "Category X" ==

[wikilist|category-x|title=Category X]

== Info articles about Category X ==

[wikilist|category-x|namespace=Info]

You can add tags to an article from the article's edit page.

Lists

Usable in: Category Pages, Item Pages, and Wikis.

We've been using lists all over this example page, so you've already seen simple lists in action. In the list of font styles directly above, for example, notice how an asterisk at the beginning of each item in our wiki syntax produced a bulleted list item on the actual wiki article.

But let's say you need to create a really complicated list, with lots of sub-sections. Simple bullets won't cut it there. But don't despair! You can create complex lists.

Add an asterisk for each level you would like a sub-section indented in your list. So, if one asterisk produces a regular bullet, two asterisks indent the bullet, three asterisks indent the bullet even further, and so on. These indents show the relationship between sections and sub-sections, as you can see in the example below.

If you'd like to use a numbered list, just insert a pound sign (#) instead of an asterisk. You can mix numbered and unordered lists, but you must be consistent within each list.

Here's an example of a complex list with sub-sections and numbered items:

* Macs
** Mac Laptops
### iBook
### MacBook
### ...
** Mac Desktops
### iMac
### Mac mini
### ...
* iPods
## Mini
## Nano
## ...

That jumble of pound signs and asterisks becomes the following:

  • Macs
    • Mac Laptops
      1. iBook
      2. MacBook
      3. ...
    • Mac Desktops
      1. iMac
      2. Mac mini
      3. ...
  • iPods
    1. Mini
    2. Nano
    3. ...

Note that exactly one new line separates each line of the list. Putting a blank line between two lines of a list will result in two lists, which isn't usually what you want.

Manual Line Breaks

Usable in: Category Pages, Item Pages, and Wikis.

The line spacing automatically widens every time you start a new line of text, as the wiki assumes you are beginning a new paragraph. If you'd like to start a new line without the spacing adjustment, simply break the line manually, using the [br] tag. The new line will then revert to standard spacing.

So, let's say you're a fan of Willie Nelson's iconic version of "On the Road Again," and you'd really like to put the lyrics on a wiki. Of course, lyrics have an awful lot of line breaks, which means the wiki will automatically elongate the spaces between lines. Your lyrics will look like this:

On the road again—

Just can't wait to get on the road again.

The life I love is making music with my friends

And I can't wait to get on the road again.

That's a lot of space between lines. Just use the [br] tag to go back to less "roomy" spacing—like this:

On the road again—[br]
Just can't wait to get on the road again.[br]
The life I love is making music with my friends[br]
And I can't wait to get on the road again.[br]

And voila! The extra space disappears:

On the road again—
Just can't wait to get on the road again.
The life I love is making music with my friends
And I can't wait to get on the road again.

Clear

If you ever find that text or images are just not floating how you'd like, you can add a clear tag. This will force a break between the aligned image or text and the other non-aligned element.

Page Redirects

Use the Redirect tag to display information from one page to another page of the same type.

For example, if you would like to see the information from Category A displayed on Category B, you would put the following wiki syntax on Category B's page:

[redirect|Category A]

Paragraphs

Usable in: Category Pages, Item Pages, and Wikis.

Paragraphs happen more-or-less automatically, so you shouldn't have to think about them too much.

Here's how they work: Any time you separate lines of text with a blank line, each block of text is made into a paragraph (unless it's a list or a heading). A good rule of thumb is to separate each logical thing in your document with a blank line.

Below is a simple example of how to separate paragraphs with blank lines in a wiki:

=== A Simple Example ===

The stuff written here makes up the first paragraph of this example.

Since the previous paragraph is separated from this text with a blank line, these lines become the second paragraph. Now, here is a list for the paragraph:

* A list with a few items:
** Item one.
** Item two.
** Item three.

Now that one more blank line has been added, we can move on to the third and final paragraph. Here endeth the lesson.

That wiki syntax yields this simple set of paragraphs:

A Simple Example

The stuff written here makes up the first paragraph of this example.

Since the previous paragraph is separated from this text with a blank line, these lines become the second paragraph. Now, here is a list for the paragraph:

  • A list with a few items:
    • Item one.
    • Item two.
    • Item three.

Now that one more blank line has been added, we can move on to the third and final paragraph. Here endeth the lesson.

Go back to the Help Index

Was this article helpful to you?

Yes
No

Didn't find the answer you were looking for?

Ask a Question
Creative Commons License
Materials Engineering Equipment Safety by The Cal Poly MatE Community is licensed under a Creative Commons Attribution 4.0 International License.
Based on a work at http://matecalpoly.dozuki.com/.