Overview

Webiki is a Movable Type plugin that provides automatic linking for posts. A post can be tagged with a “webiki word” by putting the webiki word in the “keywords” list for the post. webiki words can be separated by any combination of space, comma or semi-colon. After than, the use of the webiki word in another post will be converted to a link to the tagged post. This makes it easy to have standard explanatory posts which can be very easily referred to from other posts.

Basics

A webiki word must be mixed case, i.e. contain a mix of upper and lower case letters. The precise rules are

  • The first character must be an upper case letter.
  • If the second character is a lower case letter, digit, dash or underscore, then the rest of the webiki word can be any mix of upper case, lower case, digits, dash or underscore as long as at there is at least one upper case letter.
  • If the second character is upper case, then the rest of the webiki word can be any mix of upper case, lower case, digits, dash or underscore as long as there is at least one lower case letter, digit, dash or underscore.

Examples:

BobNo
MBobYes
BobDudeYes
BobYouRockYes
MBobYouRockYes
B2BYes
BBBNo
BBBsYes

To use a webiki word, simply type the word in another post. The Webiki filter will detect it and convert it to a link. The link text will be the title of the target post. If the target post has an excerpt set, that will be used as the link title. It is possible to configure Webiki to make the link a specific CSS class to support Webiki specific formatting.

You can also add an anchor to a webiki word by writing ‘#anchor’ immediately after the word, where ‘anchor’ is replaced by the actual anchor, for instance ‘WebikiWord#guide’.

If the character ‘!’ is placed directly before a webiki word then the ‘!’ is removed and no other processing is done. This is useful if one wants to write a webiki word without having it turned in to a link (a feature used extensively in this post).

Advanced Usage

In addition to its basic use, Webiki has a number of more sophisticated capabilities.

Formatting

Sometimes the basic formatting of Webiki is not quite what is desired. Webiki has an alternate format which allows a greater amount of control for when that is desired. This format looks like this:

[(class)[prefix]WebikiWord#anchor|text(glue)M(p-glue)[suffix]]

Impressive, isn’t it? However, it will be rare to use all of this at the same time1, although all of it is useful. All of the fields are optional except for WebikiWord. Most fields are only useful when there is more than one entry with the specific webiki word. In that case, a link for every such entry is generated.

class
Class attribute for the links. This is useful if you want to control the appearance of the link with a stye sheet.
prefix
Text to put in front of every link.
WebikiWord
The webiki word.
anchor
An anchor to attach to the URL for every link.
text
Link text to use instead of the title of the entry with the webiki word. This is useful if you want to use an alternate description or need to control the precise capitalization or plurality of the text.
glue
Text to put between pairs of links.
p-glue
Text to put between the penultimate and last links for the webiki word. This can ony be used if glue is also used.
M

The glue mode. This must be the character ‘-’ (“alternate” mode) or ‘+’ (“combine” mode). It can be omitted even if both glue and p-glue are present, in which case “mixed” mode is used. The mode should only be specified if both glue and p-glue are.

Alternate mode means that only p-glue is used for the final glue. Combine mode means the final glue is glue followed by p-glue2. Mixed mode means that alternate mode is used if there exactly two links (i.e., only p-glue is used), and combine mode if there are three or more links.

suffix
Text put after every link.

The two most common uses of this syntax are handling the plural problem and using an alternate description. By using the brackets, additional text can be attached to the end of the link text while allowing Webiki to recognize the word. For instance, something like “[WebikiWord]s”. Alternate text would look like “[WebikiWord|this plugin]”. This is modeled directly on common Wiki usage.

Glue and the affixes are useful only for multi-entry webiki words. In particular, glue will never be used with webiki words that have only one entry. The use cases for these two features do not overlap, meaning that in practice you will use one or the other but not both.

Glue is useful for links in line to put conjunctions between the links. The defaults are “, ” and “ and ” in mixed mode. This yields output like “link and link” or “link, link, link, and link”. For example, this

[WebikiPage|here( &ndash; )-( <b>and</b> )]

lets us talk about the posts for Webiki hereherehere and here.

The affixes are useful for more structured formatting. For instance, to put the entries in a list, one could use

<ul>[[<li>]WebikiPage[</li>]]</ul>

to get3

Tags

Webiki supports several tags for Movable Type templates.

MTWebikiVersion
Generate text that is the version number of Webiki.
MTIfWebikiWords
A conditional tag that is true if an entry has any webiki words. By default this is the current entry. If the “entry_id” attribute is present, the value is used as the entry ID instead of the current entry.
MTWebikiWords
A container tag that executes its contents once for each webiki word defined for an entry. By default this is the current entry. If the “entry_id” attribute is present, the value is used as the entry ID instead of the current entry.
MTWebikiLinks
A container tag that iterates over the targets of a webiki word. The webiki word is the value of the “word” attribute, or the current webiki word if that attribute is omitted. The current entry (if any) is excluded unless the “me” attribute is set to a true value (such as “too”).
MTIfWebikiLinks
A conditional tag that is true if a webiki word has targets. The webiki word is the value of the “word” attribute, or the current webiki word if that attribute is omitted. The current entry, if any, is not considered unless the “me” attribute is set to a true value (such as “too”).
MTWebikiRelatedLinks
A container tag that iterates over all the targets of all webiki words for an entry. This entry is either the entry with the identifier of the value of the “entry_id” attribute, or the current entry if that attribute is omitted. Targets that reference the entry are elided unless the “me” attribute is set to a true value (such as “too”). Only MTWebiki value tags are supported in this container, not MTEntry tags. This tag supports the attributes “sort” and “reverse” as well, which use the same values as the configuration settings.
MTIfWebikiRelatedLinks
A conditional that is true if MTWebikiRelatedLinks would iterate over at least one target. It accepts the same attributes as MTWebikiRelatedLinks.
MTIfWebikiEntries
A conditional tag that executes its contacts if a webiki word has any target entries. The word can be specified with the “word” attribute or, if that is absent, the current webiki word for the MTWebikiWords container. The current entry, if any, is automatically excluded unless the attribute ‘me=”too”’ is present. All standard MTEntry tags are avaiable in this container.
MTWebikiEntries
A container tag that operates just like the MTEntries tag except that it selects entries for a webiki word. The attribute “word” is used to specify the webiki word. If not present the current webiki word for the MTWebikiWords container is used. The contents of the container will be repeated once for each entry that is a target of the webiki word, except the current entry unless the ‘me=”too”’ attribute is present. All of the standard MTEntry tags work inside this container.
MTWebikiRelatedEntries
A container tag that iterates over all entries that share a webiki word with a specified entry. The latter can be specified by setting the “entry_id” attribute value to the identifier of the desired entry, or if that attribute is missing it is the current entry if any. The specified entry is elided unless the “me” attribute is set to a true value (such as “too”). All MTEntry tags are available in this container. This tag supports the attributes “sort” and “reverse” as well, which use the same values as the configuration settings.
MTIfWebikiRelatedEntries
A conditional tag that is true if MTWebikiRelatedEntries would iterate over at least one entry. It processes the same attributes as MTWebikiRelatedEntries.
MTWebikiWord
A value tag that evaluates to the current webiki word for any of these container tags.
MTWebikiURL
A value tag that evaluates to the URL for the current webiki word target for MTWebikiLinks and MTWebikiRelatedLinks container tags.
MTWebikiText
A value tag that evaluates to the link text for the current webiki word target for MTWebikiLinks and MTWebikiRelatedLinks container tags.
MTWebikiTitle
A value tag that evaluates to the link title for the current webiki word target for MTWebikiLinks and MTWebikiRelatedLinks container tags.
MTIfWebikiTitle
A conditional tag that is true inside a MTWebikiLinks and MTWebikiRelatedLinks container tags when the current webiki word target has a title.
MTWebikiPerformanceData
This generates output that is useful in analyzing the performance of Webiki.

This is a lot of tags, but deciding which ones to use is straightforward, as described in this handy chart.

  • I want to iterate over the targets of a specific webiki word.
    • I want to use MTEntry tags.
      • ⇒ UseMTWebikiEntries.
    • I want to include external webiki words.
      • ⇒ Use MTWebikiLinks.
  • I want to iterate over the targets of an entry.
    • I want to process the targets of each webiki word together.
      • I want to use MTEntry tags.
        • ⇒ Use MTWebikiWords with a nested MTWebikiEntries.
      • I want to include external webiki words.
        • ⇒ Use MTWebikiWords with a nest MTWebikiiLinks.
    • I want to process the targets as one big group.
      • I want to use MTEntry tags.
        • ⇒ Use MTWebikiRelatedEntries.
      • I want to include external webiki words.
        • ⇒ Use MTWebikiRelatedLinks.

As an example, this template code could be added to an individual archive template to generate a “releated posts” list. Because the current entry is be default excluded, the list will contain only references to other posts and will generate no output for webiki words defined only in the current post. So, according to the chart, we want to iterate over targets for an entry in one big group as entries.

<MTIfWebikiRelatedEntries>
  <p>Related Entries:</p><ul>
  <MTWebikiRelatedEntries>
    <li><a href="<MTEntryPermalink>"><MTEntryTitle></a></li>
  </MTWebikiRelatedEntries>
  </ul>
</MTIfWebikiRelatedEntries>

Another example (which is used here) is to have a list of links in a sidebar that relate to a particular topic. In this case we want to iterate over targets for a specific webiki word.

<MTIfWebikiLinks word="WebikiWord">
  <MTWebikiLinks word="WebikiWord">
    <a href="<MTWebikiURL>"><MTWebikiText></a><br />
  </MTWebikiLinks >
</MTIfWebikiLinks >

Now, to add any entry to this list, one simply puts “WebikiWord” in the keywords for that entry. This will also include any external webiki words so that references to external URLs can be put in the list as well. To incude only local entries, just use MTWebikiEntries instead of MTWebikiLinks and switch the MTWebiki tags to MTEntry tags. This latter is exactly how the “Plugins Used” listing in the left sidebar is generated. When I ever I use or stop using a plugin, I just edit the keywords for that post4.

Other notes and caveats

If glue and affixes are used at the same time, affixes bind tighter than glue.

When glue is combined, multiple spaces are converted to single spaces.

The set of target entries for a webiki word automatically excludes the current entry. However, this is not accurately shown on the preview from the Movable Type entry editor.

The MTWebikiWords container tag does not enumerate all keywords of an entry, only those keywords that are webiki words.

If Webiki is used with Textile via FormatStack, it is important to have Webiki operate before Textile if one wants to use webiki words that have three or more upper case letters in a row. Textile will convert these to SPAN elements, rendering them invisible to Webiki.

Install and Configuration

If you’re interested in Webiki, here are instruction for Installing Webiki and a more technical guide about Configuring Webiki.

You will also want to enable the ‘Keyword’ and ‘Excerpt’ fields in the Movable Type interface. To do this, edit a post (it doesn’t matter which one). Down under the section with the editable fields of the post is a link reading ‘Customize the display of this page.’. Click on that link. In the popup, select the ‘Custom’ option and then the ‘Excerpt’ and ‘Keyword’ checkboxes. These should now be enabled on the post editing page.

Example

On the post for the install guide, I added the text ‘WebikiInstall’ to the ‘Keywords’ field and saved that post. Then, in this post I wrote the text ‘instructions for WebikiInstall’. Webiki detected the webiki word and converted it to a link (if you’re wondering how I prevented that for this example, I used a leading ‘!’).


1 I have not found a use case where all of it makes sense. Let me know if you do!

2 After glue and p-glue are combined, multiple spaces are converted to single spaces.

3 That’s not really what I use here, because I use Textile for formatting. That means I can do this instead:

[[* ]WebikiPage[
]]

4 In fact, one could do a blogroll this way, although I don’t think it’s the optimal approach. To do so, one would add external webiki words to the settings, each with the webiki word “BlogRoll”. Then the blog roll is simply

<MTWebikiLinks word="BlogRoll">Blogroll: <br />
  <a href="<MTWebikiURL>" title="<MTWebikiTitle>"><MTWebikiText></a>
  <br />
</MTWebikiLinks >