Adding lists in MediaWiki

Introduction

This is a follow-up article to the ongoing postings regarding adding content in MediaWiki. The plan is to add more short posting about adding content to MediaWiki. This posting talks about lists.

You can create 3 types of lists in MediaWiki:

  • Unordered lists
  • Ordered lists
  • Definition lists

Unordered lists

Unordered lists are just the normal bullet lists probably familiar from word processing software or plain HTML. You create a new list element by using an asterisk (*) at the beginning of each line. It is important that the asterisk is at the beginning of the line for it to work. You can have no whitespace between the line start and the asterisk. The number of asterisk characters indicates the list element level, so for example:

* First element
** First sub-element
*** First sub-sub-element
** Second sub-element
* Second element
etc.

Will create an unordered list that gives the following output:

Unordered list example in MediaWiki

Ordered lists

Ordered lists are pretty much more of the same. However, you use the hash character (#) instead of the asterisk. To restart the automatic numbering you must insert a blank line within the list, so

# First element
## First sub-element
### First sub-subelement
## Second sub-element
# Second element

Gives the following output

An example of an ordered list

Combining unordered and ordered lists

It is also possible to combine the two list types to make any kind of crazy combination. Check out the following example:

# element 1
# element 2
#* element 3
#* element 4
#** element 5
#** element 6
## element 7
##* element 8
##** element 9
# element 10

Which gives this result:

Combining unordered and ordered list elements in a crazy partnership

Definition list

A definition list is a list type you expect to find in a dictionary or a glossary. The syntax is a bit different from it’s list siblings:

;First definition : definition text
;Second definition : definition text

So here we have two definition keys with their matching text definition. The output looks like this:

Example of definition list output

The definition text itself can expand over multiple lines and can also contain semicolon (;) characters as part of the text as long as the semicolon is not at the beginning of a new line. Like the other list types it is very important not to type any whitespace between the semicolon and the beginning of the new line. The colon character, however, defining the definition list, can be placed just about anywhere you like.

Advertisements

Removing default search limitations in MediaWiki and MySQL

Introduction

So let’s assume you have created a page in your Mediawiki site, named it with an appropriate page title consisting of only 3 characters, say SSL or SQL, only to find that it never shows up when searching for it in the MediaWiki site search. You have tried both uppercase and lowercase search query words, you haven’t misspelled the search query (only 3 characters, after all), and you are certain you are searching through the correct MediaWiki namespace. You are also certain that you saved the page, not only previewed it and then made the mistake of closing your browser.

Come to think of it, that page you are 110% certain you read yesterday, referring to the exact same search query word, say ‘SSL’, doesn’t show up either when searching for either of ‘ssl’ or ‘SSL’. How can that be? You didn’t delete the page by mistake, did you? This is getting annoying, but are you starting to see a pattern?

As we will see this has nothing to do with searching the wrong MediaWiki namespace (although easy enough to do), misspelling the search query word, distinguishing between uppercase or lowercase search query words, failing to save a page edit or deleting a page by mistake. The cause is simple: by default, the MySQL database server does not fulltext index words of 3 characters or below. To make this possible, you will have to change the configuration of both MediaWiki and MySQL to enable it to search for useful words and abbreviations of character length 3, such as apt, ssh, nfs and the like.

Editing the MediaWiki configuration

It is simple to correct this problem, but you need access to both the web server file system and administrator privileges to the MySQL database server. Locate the LocalSettings.php file in your MediaWiki installation directory, usually a subdirectory of your web server’s document root, say /htdocs on Apache. Edit the file and add the variable wgDBminWordLen to it. Set it’s value to 3, so:

$wgDBminWordLen = 3;

Editing the MySQL configuration

You must also tell the MySQL database server to index 3-letter words in fulltext indexes. This is the core of the problem and this configuration change will also apply to any application using the MySQL database server, not just MediaWiki. Add or edit the [mysqld] heading in your my.conf file with the following configuration line:

[mysqld]
ft_min_word_len=3

And that’s really all there is to it!

Recreate the MySQL table index

So just one more step to go before you can use it. You now need to restart your MySQL database server to load the new configuration setting, and then recreate the search index. So restart your server process, open a console and proceed to enter the MySQL database you use for your MediaWiki installation. Recreate the necessary search index by typing:

REPAIR TABLE searchindex QUICK;

If you prefixed your MediaWiki database tables with a prefix when installing the wiki then the name of your ‘searchindex’ table may be wk_searchindex or similar. A simple ‘show tables;’ query will give you a hint of the correct table name.

Summary

This particular fix took me a little while to find. Not that it was hidden, but I was unsure which component was limiting the search. As you have seen it turns out both MediaWiki and MySQL needed to be tweaked to correct the problem. Remember there is a reason why MySQL sets the index limitation to 3 characters by default. By changing it you will increase your index sizes leading to a performance hit. The default setting is 4 characters and I’m sure there is a statistical reason for this. Take a closer look at this page for more information on tuning the fulltext search in MySQL if you are unsure of the impact it might have.

The power of your own personal wiki

Introduction

It’s only human. Over time you are destined to forget information and recycle it with fresh knowledge. You do this unintentionally. It seems that even the latest neuron based harddrives, encapsulated inside the human brain, have a limited size capacity before information is either archived or sent to /dev/null. The logical strategy is, of course, to store the important information externally, outside the body, for future reference.

The problem domain

I try to keep up to date on a broad variety of mostly open source technology. The usual trend is to acquire an taste for something, learn enough about it to test it and form an opinion, and then forget all about it. That is, of course, unless I can use it for something immediately. In which case the information may stick if I’m lucky.

Some time back I was configuring a lot of Linux software, mostly for my own personal home use. On many occasions I would find myself in a situation where I would need to repeat a process that I knew I had performed earlier. Although Google is a good friend, I was getting frustrated with myself for wasting time acquiring knowledge only to use it once and then throw it away. I was more or less starting over, every time. My first solution was to persist the freshly gained knowledge to text files.

Prelude to the “battle”

I was quite happy with the solution for a while, but something was still wrong. The second part of the problem was becoming apparant. It wasn’t that things weren’t getting documented in some form or fashion as expected, but I was missing the necessary functionality to reclaim the information when I needed it. Plain text files only get you so far, and although easy to access from a wide variety of user interfaces, they allow for mostly simple read and write access, but not search (Yes, I am aware of grep).

On Linux, using text files is considered the normal thing to do. Most system and application configuration is stored in plain text files so at first this didn’t strike me as abnormal. However, when the number of text files started to reach double figures, together with poorly chosen file names, and grep wasn’t helping me, I concluded that the time had come to bring out the big guns.

Introducing the Wiki

I’m sure most of you know what a Wiki is, but in the event you do not, then let me introduce WikiPedia as the best evidence of a great wiki implementation. It is the largest multilingual encyclopedia available online, containing more than 2 million articles and growing. In general, a wiki is a browser-based collaborative writing environment, to which anyone may contribute without having web programming or publishing skills. It is software that is used to create and display collaborative content, usually without intervention from an administrator or editor.

I began using a personal wiki instead of text files and the success was immediate. Reading, writing, searching and categorizing the documentation was a piece of cake. I can also let others use my wiki should I choose without giving them access to my file system.

MediaWiki software – open source, of course

A lesser known fact is that WikiPedia runs on open source software, created by the WikiMedia Foundation for the WikiPedia project. It is freely available under an open source license for anyone to download and use. The software’s name is MediaWiki and is written in PHP. I will only be discussing the MediaWiki software in this blog entry.

Prerequisites and installation

The easiest way to run MediaWiki is using the Apache web server, PHP and MySQL. All are open source software and form three of the four components of the defacto LAMP software setup. You don’t need to use Linux as your operating system to run MediaWiki, but if you should choose to then your installation will be relatively easy to setup and configure. The aforementioned software packages are normally a part of most common Linux distributions or easily available from the distribution software repository, so you won’t need to download or update a thing – the OS will do it for you. I will avoid going into details on how to install Apache, PHP or MySQL for other systems since there already exists much well written documentation and tutorials for each of these packages online. Remember, Google is your friend.

Let me also add that you will need PHP version 5 or above and MySQL 4 or above. It is now also possible to use PostgreSQL as a replacement for MySQL, should you prefer. In which case you will need version 8.1 or above. You can also replace Apache and use Microsoft IIS as your web server, but surly only someone insane would want to do that…

Of course, you will also need to download the actual MediaWiki software which, as mentioned previously, is also open source. Unpack it to your Apache server document root (usually the htdocs directory) and rename the resulting directory to “wiki”. You should then be able to access the MediaWiki setup wizard from a URL of form “http://yourhost/wiki”. Follow the instructions carefully. If memory serves me correctly, you will need some basic MySQL knowledge, but the tables etc are created automatically on setup. The web server will need write access to the MediaWiki’s “config” directory to store the resulting configuration, but you will be informed should a problem present itself.

Here are two screen shots of how things should look when you start the web based installation wizard.

Initial setup wizardThe MediaWiki installation wizard appears

Has the jury reached a verdict?

Next it’s time to add some wiki content, but this blog entry is just getting too long, so let’s leave it at that for now. Make sure you call back some time later and I’ll introduce some of MediaWiki’s nifty formatting features. Adding web content has never been easier and the results look great.