Emanuele Santanche
WYSIWYG editor for Mediawiki

What Mediawiki is and what it is for

Mediawiki is the engine that powers Wikipedia. It’s a wiki and it’s used to create collaborative websites where people can share knowledge and keep all sorts of information.

They make it possible for people to work on the same document.

Personally I keep most of my information in Mediawiki websites.

Mediawiki is very good to create intranets, website used internally in an organization.

How to make editing easier

Many people find editing wiki pages difficult. Even if you get a standard tool bar and you don’t have to remember wiki syntax, there are some things that are difficult to edit and maintain.

Tables are one of them. it’s easy to create a table because Mediawiki offers a wizard that guides you. But it’s not so easy to edit the table, to add rows and columns, to edit the content.

WYSIWYG editor

A WYSIWYG editor is, in general, an editor that makes it easier to work on a document.

In our case a WYSIWYG editor hides Mediawiki syntax so that you don’t have to remember it at all. You just edit the document in the same way you would edit a document created with a word processor.

Visual editor

Visual Editor is our WYSIWYG editor. Wikipedia uses it as well.

The starting point to find information about it is its Mediawiki extension page.

Installing Parsoid

Before installing Visual Editor, we have to install Parsoid. It’s a server process that converts HTML code into Mediawiki syntax and back.

The WYSIWYG editor works on HTML code. It keeps our editing activity in HTML form. But it has to eventually convert that HTML into Mediawiki syntax otherwise Mediawiki won’t be able to store it.

When it has to save a page to Mediawiki database, Visual Editor takes the HTML version of the document and gives it to Parsoid. The latter converts it into Mediawiki syntax and Visual Editor gives that syntax to Mediawiki for it to store in the database.

The package

To install Parsoid we need to add a repository to our Debian software sources. My server runs Debian Jessie (version 8).

  1. echo "deb https://releases.wikimedia.org/debian jessie-mediawiki main" | sudo tee /etc/apt/sources.list.d/parsoid.list

You may have to add an authentication key to access the repository. This is generally done with a command like the following one:

  1. sudo apt-key advanced --keyserver keys.gnupg.net --recv-keys 90E9F83F22250DD7

The actual key may be different.

Now let’ install the package.

  1. root@FREEDOMANDCOURAGE:/etc/apt/sources.list.d# sudo apt-get update

  2. root@FREEDOMANDCOURAGE:/etc/apt/sources.list.d# sudo apt-get install parsoid

You may need to install the package apt-transport-https as well.

Configuring Parsoid

There are many files to configure for Parsoid to work.

Config.yaml

The main one if config.yaml (/etc/mediawiki/parsoid/config.yaml).

You find there a line like this:

  1. http://localhost/w/api.php

This is needed for Parsoid to access Mediawiki apis. Parsoid uses Mediawiki apis to return the result of the conversions it performs.

I have many websites on my server. I need to replace localhost with my Mediawiki installation domain.

Something like mediawiki.example.com. Your domain will be different.

In my case api.php is directly on the root of the website. Like http://mediawiki.example.com/api.php. If you browse to your api.php, you get some help information, if it’s working.

LocalSettings.php

We have to add lines to the LocalSettings.php file of our Mediawiki installation.

This Mediawiki installation is private. It’s like an intranet. You need userid and password to access it.

This means that Parsoid needs to be authorized to access Mediawiki when it sends back to Mediawiki the result of the conversions it performs.

This is what we do first thing in our LocalSettings.php file.

The line with the URL to the Parsoid instance is interesting. It tells us that Parsoid is a server process listening on port 8142. Mediawiki will contact it at that port when needing to convert HTML code into Mediawiki syntax.

Also the line about forwarding cookies is essential for Parsoid to work with a private Mediawiki installation.

  1. // Authorizing Parsoid to access Mediawiki

  2.  

  3. if ( $_SERVER['REMOTE_ADDR'] == '127.0.0.1' || $_SERVER['REMOTE_ADDR'] == 'localhost' ) {

  4.    $wgGroupPermissions['*']['read'] = true;

  5.    $wgGroupPermissions['*']['edit'] = true;

  6. }

  7.  

  8. wfLoadExtension( 'VisualEditor' );

  9.  

  10. // Enable by default for everybody

  11. $wgDefaultUserOptions['visualeditor-enable'] = 1;

  12.  

  13. // Optional: Set VisualEditor as the default for anonymous users

  14. // otherwise they will have to switch to VE

  15. // $wgDefaultUserOptions['visualeditor-editor'] = "visualeditor";

  16.  

  17. // Don't allow users to disable it

  18. $wgHiddenPrefs[] = 'visualeditor-enable';

  19.  

  20. // OPTIONAL: Enable VisualEditor's experimental code features

  21. $wgDefaultUserOptions['visualeditor-enable-experimental'] = 1;

  22.  

  23. $wgVirtualRestConfig['modules']['parsoid'] = array(

  24.    // URL to the Parsoid instance

  25.    // Use port 8142 if you use the Debian package

  26.    'url' => 'http://localhost:8142',

  27.    // Parsoid "domain", see below (optional)

  28.    //'domain' => 'localhost',

  29.    // Parsoid "prefix", see below (optional)

  30.    //'prefix' => 'localhost'

  31. );

  32.  

  33. # This is for parsoid when it works, like in this case, on a private Mediawiki installation

  34. // This feature requires a non-locking session store. The default session store will not work and

  35. // will cause deadlocks (connection timeouts from Parsoid) when trying to use this feature.

  36. $wgSessionsInObjectCache = true;

  37.  

  38. // Forward users' Cookie: headers to Parsoid. Required for private wikis (login required to read).

  39. // If the wiki is not private (i.e. $wgGroupPermissions['*']['read'] is true) this configuration

  40. // variable will be ignored.

  41. //

  42. // WARNING: ONLY enable this on private wikis and ONLY IF you understand the SECURITY IMPLICATIONS

  43. // of sending Cookie headers to Parsoid over HTTP. For security reasons, it is strongly recommended

  44. // that $wgVirtualRestConfig['modules']['parsoid']['url'] be pointed to localhost if this setting is enabled.

  45. $wgVirtualRestConfig['modules']['parsoid']['forwardCookies'] = true;

Installing Visual Editor

To install Visual Editor, we need to follow the standard procedure.

From the Extension Distributor we download Visual Editor for our Mediawiki version, 1.28.

Then we extract it in our extension folder.

Many lines need to be added to our LocalSettings.php file and you see them above.

To be sure that the extension has been installed, we visit the Version page, for example https://mediawiki.example.com/index.php?title=Special:Version.

Using Visual Editor

Visual Editor makes creating and editing tables much simpler. Mediawiki tables have a quite complicated syntax and it isn’t easy to edit them or add row and columns if you don’t have Visual Editor.

Other functions are facilitated and enhanced wizards are available to perform most of them.

There is a good user guide.

Visual Editor problems

The are a few problems when using Visual Editor.

It can be slow when staring editing. Sometimes I use the default editor. To do so, I just have to click on “edit source”.

If you insert more than one code block in a page, they will disappear from the WYSIWYG view. You will have to switch to the default editor to edit them.

This is a bug that may be solved in the future.

Some pages can’t be edited using Visual Editor. You will have to use the default editor.

Emanuele Santanche
Privacy policy