MediaWiki notes

From Noah.org
Jump to: navigation, search


MediaWiki is great wiki software. It's easy to install and setup and it's easy to hack. Here is a list of my pet peeves. None of these stop me from using it.:

  • Silly default setting were Wiki_words_must_start_with_capital_letter. This is incredibly annoying for article titles where capitalization makes a difference (like virtually any article on computers). Why shouldn't my titles start with a lower case letter? Luckily, this is an option that you can set, but if you have an old wiki database that you have been using for a while it can be a hassle to try to convert article titles. See #Turn off annoying Wiki-style capitalization.
  • User management sucks. Their policy is that user management is not part of their mission, but it's a pain to even reset a user's password.
  • Group management. There is almost no support for groups or even trivial access rights. You can't control read-only or no-access for groups of users to groups of pages. Again, this isn't part of their mission, so they don't support it. There are extensions to help with this.
  • Wiki markup is certainly easier to read and write than HTML, but only marginally so. It's frustrating because the syntax isn't far from something readable like reStructuredText, but it fails. It's harder than it needs to be for non-technical people to use. MediaWiki tables suck. They are not much simpler than HTML tables! And preformatted sections suck!
  • Templates and styles are ugly. They are easy to hack, but it's difficult to feel like you are doing it right. It is far from elegant. It's a big mash of HTML, Javascript, CSS, and PHP. I have experienced the opposite with content management systems that are based on incredibly opaque, complex object models that make every single concept in the system so abstract that you have to study the system for a week before you feel like you can begin to grasp the weird alien logic that conceived of such a system. Eventually you realize the system was conceived of by stupid humans and you've spent a week getting your helloWorldImplViewObserverFactoryEventHandlerable object to do something other than throw exceptions, but not actually display a web page... and, well, it just turns out to be a big disappointment. So, I'm happy with MediaWiki despite some of the mess.

MediaWiki documentation

Editor's Help

Developer's Manual contains good stuff on PHP source and SQL schema.

Turn off annoying Wiki-style capitalization

MediaWiki-style capital links is dumb. Nobody on Wikipedia uses it anymore, but the legacy still causes every article to begin with a capital letter. Fortunately, you can turn this off. If you set this on an existing wiki you will probably break links.

http://www.mediawiki.org/wiki/Manual:$wgCapitalLinks

Put this in LocalSettings.php:

$wgCapitalLinks = false;


Link to file

[[media:document.pdf]]

Images

basic
[[Image:example.jpg|Sunflowers]]
thumbnail
[[Image:example.jpg|center|thumb|100px|Sunflowers]]
frameless
like thumbnail, but no frame or caption: [[Image:example.jpg|frameless]]
gallery
<gallery>
Image:image1.png|Name of Image 1
Image:image2.png|Name of Image 2
Image:image3.png|Name of Image 3
</gallery>

media:igbtAPPguide.pdf

Quick table overview

Wikitext markup is not as easy and smart as it should be. In particular, tables are only slightly less annoying than they are in HTML. The following short review is copied from the MediaWiki Help:Tables page.

{| table start
optionally add style info after table start:
{| cellpadding="5" cellspacing="0" border="1"
|+ table caption, optional; only between table start and first table row
|- table row,
! table header cell, optional. Consecutive table header cells may be added on same line separated by double marks (!!) or start on new lines, each with its own single mark (!).
| table data cell, required! Consecutive table data cells may be added on same line separated by double marks (||) or start on new lines, each with its own single mark (|).
|} table end

Simple Table Examples

apple cat 12333.00
orange dog 500.00
grape parrot 1.00
{| border="1"
|-
| apple  ||   cat  || 12333.00
|-
| orange ||   dog  || 500.00
|-
| grape  || parrot || 1.00
|}

Note that the table above and the table below are equivalent.

apple cat 12333.00
orange dog 500.00
grape parrot 1.00
{| border="1"
|-
|apple
|cat
|12333.00
|-
|orange
|dog
|500.00
|-
|grape
|parrot
|1.00 
|}

The table below adds a table caption, header row, border formatting, and aligns the numbers to the right.

Table of unrelated items.
Fruit Animal Number
apple cat 12333.00
orange dog 500.00
grape parrot 1.00
{| border="1" cellpadding="5" cellspacing="0"
|+ Table of unrelated items.
|-
! Fruit  !! Animal !! Number
|-
| apple  ||   cat  || align="right"|12333.00
|-
| orange ||   dog  || align="right"|500.00
|-
| grape  || parrot || align="right"|1.00
|}

Navigation side-bars

Just edit this: MediaWiki:Sidebar

Table Of Contents Directives

Sometimes you want see the table of contents index before the article even if it is short (fewer than four sections gets no TOC). Sometimes you don't want to see a long index for a page that is essentially an index itself.

This will force the TOC to display even if there are fewer than four sections:

__TOC__

This appears to be equivalent:

__FORCETOC__

This will never display the TOC:

__NOTOC__

Change a user's password

If a user forgets their password you must reset it directly in the database. The user_password is the MD5 hash of the user_id + '-' + the MD5 hash of the plaintext password. The following examples set the password for user #1 to 'plaintext_password'.

MySQL:

UPDATE user SET user_password=md5(CONCAT('1-',md5('plaintext_password'))) WHERE user_id=1;

Postgres:

UPDATE user SET user_password=md5('1-'||md5('plaintext_password')) WHERE user_id=1;

MediaWiki makes it clear that user rights and security are not a high priority, but some of the user management borders on absurd!

Import WikiPedia database dumps

It isn't too hard to create your own local copy of WikiPedia. You just need to install MediaWiki and MySQL; download one of the WikiPedia data dumps; then import using importDump.php.

IMPORTANT: change default wgLegalTitleChars before starting import

By default, the MediaWiki software is configured to not allow + signs in article titles, but many WikiPedia article titles have + signs. This will cause the import to fail after a few hundred articles. The trick is to edit LocalSettings.php and add this line:

$wgLegalTitleChars = " +%!\"$&'()*,\\-.\\/0-9:;=?@A-Z\\\\^_`a-z~\\x80-\\xFF";

Selecting articles in SQL directly from the database

Replace ARTICLE_TITLE with the name of the article you want to retrieve. The old_text column a misnomer, but it holds the latest article text in this context.

select old_text from revision,page,text where revision.rev_id=page.page_latest and text.old_id=revision.rev_text_id and page.page_title='ARTICLE_TITLE';

create article in category

This is a simple extension. It does not save much time, but it makes the system a little easier to use for new users.

http://www.liang-chen.com/files/extensions/articletocategory.zip

Add to LocalSettings.php:

require_once("$IP/extensions/articletocategory.php"); 

mod_rewrite for redirecting 404 errors to wiki search

No more 404 errors!

If someone requests a page on your site that does not exist (HTTP 404 error) then you can redirect that request to the MediaWiki search page and search for the URI. This also lets you search for articles just by requesting them in the URI. For example, I have an article on "Pexpect" under my MediaWiki: http://www.noah.org/wiki/Pexpect, but you can also simply request with this URL: http://www.noah.org/pexpect. This mod_rewrite rule will redirect to the Search page which will find an exact match on the name and then redirect again to the article with that name.

Basically this looks for requests that don't map to a directory or a file -- ones that would generate a 404 error. The request is then redirected to the MediaWiki search. This also strips off any .html or .htm to give a search a better chance of success. Put this after any other redirect rules you may already have.

RewriteEngine on
RewriteCond %{REQUEST_FILENAME} !-f [NC]
RewriteCond %{REQUEST_FILENAME} !-d [NC]
RewriteRule ^(.+?)(\.html|\.htm)?$ http://%{SERVER_NAME}/wiki/Special:Search?search=$1&go=Go [R=301,NC,L]

mod_rewrite for MediaWiki friendly URLs

This example assumes MediaWiki is installed in a subdirectory 1 level down from root, www.example.com/mediawiki/. This will map the virtual path /wiki to /mediawiki and will allow short, friendly URLs that map http://www.example.com/mediawiki/index.php?title=Main to http://www.example.com/wiki/Main. For more information see the MediaWiki Short URL documentation.

Modify the following options in LocalSettings.php
$wgUsePathInfo = true;
$wgScriptPath  = "/mediawiki"; # path to the real directory MediaWiki is installed in.
$wgScript      = "$wgScriptPath/index.php";
$wgArticlePath = "/wiki/$1"; # Path to the virtual directory. Should NOT exist.
Edit the .htaccess file in the root directory of www.example.com to include
RewriteEngine On
RewriteRule ^wiki$ /wiki/Main_Page [R=301,nc,L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^(.+)$ /mediawiki/index.php?title=$1 [L,QSA]

OLD SETUP mod_rewrite for MediaWiki friendly URLs

This is a pain in the ass to get right. There are not many pieces, but I had to keep fiddling with them to get it right. Plus, it's easy to get it almost but not quite right.

Assuming you want the root URI to be /wiki (just like Wikipedia). For example:

http://www.noah.org/wiki/Htaccess

Move wiki root directory

First move your wiki directory from to w/. This is the filesystem path, not the URI. For example:

mv /var/www/htdocs/wiki /var/www/htdocs/w

Just to be clear, the wiki/ directory should no longer exist in the filesystem. It will not just be a virtual directory handled by MediaWiki scripts.

MediaWiki LocalSettings.php

$wgScriptPath       = "/w";
$wgArticlePath      = "/wiki/$1";

.htaccess (above the MediaWiki directory)

RewriteEngine on

# This rewrites URIs in the form /wiki/Article_Name to /w/index.php/Article_Name.
RewriteCond %{REQUEST_URI} !^/wiki/index.php.*$ [NC]
    RewriteRule ^wiki/?(.*)$ /w/index.php/$1 [L]

# This takes old style links to articles in the form /wiki/index.php/Article_Name and
# redirects them to the new-style format /wiki/Article_Name.
RewriteCond %{REQUEST_URI} ^/wiki/index.php/.*$ [NC]
    RewriteRule ^wiki/index.php/(.*)$ http://www.noah.org/wiki/$1 [R=301,NC,L]

Static HTML dump of MediaWiki

MediaWiki can be used as a CMS for generating static HTML pages. Surprisingly nobody has made it easy to dump static content from MediaWiki.

wget

This creates static dumps of a wiki using wget. This does not hide navigation links and other links that will not have any meaning outside of the wiki engine.

step 1. Authenticate and save cookies

First you must login. You can skip this step if a login is not necessary. This authenticates and saves the auth token in cookies.txt. Note the login URL and post-data because quoting and escaping can get tricky here. Also be sure to replace or set $WIKI_USERNAME and $WIKI_PASSWORD.

wget --save-cookies cookies.txt --post-data 'wpName=$WIKI_USERNAME&wpPassword=$WIKI_PASSWORD&wpRemember=1&wpLoginattempt=Log%20in' http://www.example.com/wiki/index.php\?title=Special:Userlogin\&action=submitlogin\&type=login

step 2. Download article

Note that '--convert-links' option may not be what you want since it can destroy the table of contents at the start of the article because `wget` does not handle fragment identifiers properly.

This grabs one article into the current directory:

wget --no-parent --page-requisites --convert-links --no-host-directories --cut-dirs=2 --load-cookies cookies.txt --directory-prefix=. http://www.example.com/wiki/index.php/My_Article

This grabs one article into the current directory in <rm>printable</em> format with very minimal styling. Note also there is no '--convert-links' option.

wget --no-parent --page-requisites --no-host-directories --cut-dirs=2 --load-cookies cookies.txt --directory-prefix=. http://www.example.com/wiki/index.php\?title=My_Article\&printable=yes

This grabs everything in the wiki into the current directory:

wget --mirror --no-parent --page-requisites --convert-links --no-host-directories --cut-dirs=2 --load-cookies cookies.txt --directory-prefix=. http://www.example.com/wiki/index.php/Main_Page

mw2html.py

This project seems sort of dead and it does not support authentication.

#!/bin/sh
/usr/bin/python /var/www/usr/local/apache2/htdocs/wiki/mw2html.py --no-made-by --left=adsense.html --force -i main_page.html http://www.noah.org/wiki/index.php/Engineering /var/www/htdocs/engineering
chown -R www:www /var/www/htdocs/engineering

Articles and Subcategories swap

I don't like having Subcategories listed before Articles. I have a long list of Subcategories, so I prefer to have Subcategories listed after all of the articles. Unfortunately, there is no easy way to adjust this in a skin. Instead, I had to modify the wiki/includes/CategoryPage.php source file. The change was simple. Here is a diff of the file that I changed. Note that the line with "$this->getSubcategorySection()" was moved down two lines.

# diff -c CategoryPage.php CategoryPage.php.noah 
*** CategoryPage.php    2007-07-18 12:09:04.000000000 -0700
--- CategoryPage.php.noah       2007-07-18 12:08:24.000000000 -0700
***************
*** 85,93 ****
                $this->finaliseCategoryState();
  
        $r = $this->getCategoryTop() .
-               $this->getSubcategorySection() .
                $this->getPagesSection() .
                $this->getImageSection() .
                $this->getCategoryBottom();
  
                wfProfileOut( __METHOD__ );
--- 85,93 ----
                $this->finaliseCategoryState();
  
        $r = $this->getCategoryTop() .
                $this->getPagesSection() .
                $this->getImageSection() .
+               $this->getSubcategorySection() .
                $this->getCategoryBottom();
  
                wfProfileOut( __METHOD__ );

Include external static content

Often it is handy to include the contents of external files directly in an article instead simply linking to the file. This describes "include" -- a MediaWiki extension that lets you include external static content from the local file system; a remote URL; or a Subversion repository.

I expanded this section into its own article. For more information see the article on MediaWiki_Include.

Article Cache Purge

Sometimes you may need to purge MediaWiki's cache of a specific article. Put the following code in an article and you will get a link that will tell MediaWiki to purge the cache for that article.

{{FULLURL:{{NAMESPACE}}:{{PAGENAME}}|action=purge}}

That code will result in a link like this: http://www.noah.org/mediawiki/index.php?title=MediaWiki_notes&action=purge

Remove MediaWiki logo at bottom of page

Edit either ${MEDIAWIKI_ROOT}/skins/common/commonContent.cssand add #footer-poweredbyico { display: none; } to the end of the file. Or, for older versions of MediaWiki, edit ${MEDIAWIKI_ROOT}/skins/${wgDefaultSkin}/main.css and add #f-poweredbyico { display: none; } after the last reference of f-poweredbyico.

It's not that I'm not grateful to MediaWiki for an awesome, free Wiki; it's just that the icon adds yet more busy noise to every page.

Small words in Full Text Index

By default MySQL does not index words smaller than four characters. That makes it impossible for MediaWiki to search for words such as 'SSH' or 'FTP'. The following will correct this.

Edit /etc/mysql/my.cnf (or /etc/my.cnf) and add the following variable after [mysql] section:

ft_min_word_len = 2

Restart MySQL:

/etc/init.d/mysql restart

Rebuild full text index. You must cd into the MediaWiki install directory. For example /var/www/htdocs/wiki:

php ./maintenance/rebuildtextindex.php

Longer Maximum Article Length

http://www.mediawiki.org/wiki/Manual:$wgMaxArticleSize

debugging errors

Put this in your LocalSettings.php file:

$wgShowExceptionDetails = true;

NoFollow Links

For a private Wiki you almost certainly want to set this FALSE (default is TRUE). When set to false then your links to external sites will help boost their search engine page rank. When set TRUE search engines will not count your links. This is good if you have a public site where users might try to stuff links into your pages to boost page rank.

http://www.mediawiki.org/wiki/Manual:$wgNoFollowLinks

Allowed memory size of 20971520 bytes exhausted

I was getting blank pages sfrequnety on a new Wiki I set. There was error in the browser and nothing in the server error logs.

Mar  4 14:55:24 dev-kvm-1 apache2: PHP Fatal error:  Allowed memory size of 20971520 bytes exhausted (tried to allocate 131072 bytes) in /var/www/wiki/includes/OutputHandler.php on line 81

Most of the responses to this error I have seen say to increase the memory_limit in /etc/php5/apache2/php.ini and /etc/php5/cli/php.ini.

memory_limit = 128M ; Maximum amount of memory a script may consume (32MB)

Really, the problem was in /var/www/wiki/LocalSettings.php. Edit the file to increase memory_limit.

# If PHP's memory limit is very low, some operations may fail.
ini_set( 'memory_limit', '128M' );

LocalSettings.php

These are the options in LocalSettings.php that I usually change after I install MediaWiki.

$wgEnableUploads       = true;
$wgCheckFileExtensions = false;
$wgUseAjax = 'true';
$wgEnableMWSuggest = true;
$wgCapitalLinks = false;

# For a public read-only wiki.
# Anyone can read, but login is required to edit or create accounts.
$wgGroupPermissions['*']['edit'] = false;
$wgGroupPermissions['*']['createaccount'] = false;

# When listing articles in a given category
# I prefer to see one big list on one page.
# http://www.mediawiki.org/wiki/Manual:$wgCategoryPagingLimit
$wgCategoryPagingLimit = 32768;

## # This is for a private wiki where a user must login to do anything.
## # Note that "Special:Userlogin" is the only page allowed a visitor may read.
## $wgGroupPermissions['*']['createaccount'] = false;
## $wgGroupPermissions['*']['read'] = false;
## $wgGroupPermissions['*']['edit'] = false;
## $wgWhitelistRead = array ("Special:Userlogin");

## # This is for a corporate wiki where anybody may read as long as they
## # come from the internal LAN network. Visitors from outside the office
## # must login to do anything. This allows people inside the office
## # to read the wiki without having to login. Internal connections are
## # given "Guest" as a default user.
## require_once( "$IP/extensions/NetworkAuth/NetworkAuth.php" );
## $wgNetworkAuthUsers[] = array(
##     'iprange' => array( '10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16'),
##     'user'    => 'Guest'
## );

## # This is for a corporate wiki where some users may read only
## # and 'staff' users may read and edit.
## $wgGroupPermissions['*']['edit'] = false;
## $wgGroupPermissions['*']['read'] = false;
## $wgGroupPermissions['*']['createaccount'] = false;
## $wgGroupPermissions['staff']['edit'] = true;
## $wgGroupPermissions['user']['createaccount'] = false;
## $wgGroupPermissions['user']['edit'] = false;
## $wgGroupPermissions['guest']['createaccount'] = false;
## $wgGroupPermissions['guest']['edit'] = false;
## $wgWhitelistRead = array ("Special:Userlogin");


# This will make sure cached pages are cleared after you edit this config file.
$wgCacheEpoch = max( $wgCacheEpoch, gmdate( 'YmdHis', @filemtime( __FILE__ ) ) );

# These extensions are popular with non-technical users:
require_once("$IP/extensions/FCKeditor/FCKeditor.php");
require_once("$IP/extensions/articletocategory.php");

# This extension allows a sysop to reset user passwords.
$wgGroupPermissions['sysop']['passwordreset'] = true;
require_once("$IP/extensions/PasswordReset/PasswordReset.php");

Mail settings

This works on most systems that have a localhost MTA. You also need to make sure that your PHP install supports direct mail. The following instructions install PEAR mail support:

pear install --alldeps Net_SMTP
pear install --alldeps MAIL

Then add these settings to LocalSettings.php (change example.org to the hostname):

$wgSMTP = array(
    'host'     => "127.0.0.1",
    'IDHost'   => "example.org",
    'port'     => 25,
    'auth'     => false
#    'username' => "my_user_name",
#    'password' => "my_password"
);