Parsoid/JS

This page documents Parsoid/JS, which was replaced by Parsoid/PHP in 2020.

Setting up VisualEditor
To set up your own Parsoid service follow the Parsoid installation instructions before setting up VisualEditor. Note that it can be particularly complicated to set up Parsoid and Node.js in non-standard systems, like those running Windows or Debian.

Below is the non-official compatibility matrix between the VisualEditor on some MediaWiki version and the Parsoid service. In general, if you're running into problems with installation, getting exactly matching versions (VisualEditor, Parsoid, and MediaWiki) should be one of the first things you try, even if this table says that a mismatched set will probably work.

Caption :
 * X = tested, working
 * - = tested, non-working

Notes :
 * (a) = non-compatible with 0.6.1 (phabricator:T100681)
 * (b) = non-compatible with 0.9.0 (mailarchive:wikitech-l/2018-March/089690.html); from the version after 0.9.0 (currently unreleased) there is no more compatibility mode
 * (c) = very partially, it is possible to add text but not to modify existing text
 * (d) = issues on images for Parsoid 0.6 + MW 1.30 and probably 1.31 also (Topic:Ufpghq2hidcj3d3w)
 * 0.9 compat = either modified Parsoid code (see this blog) either a specific Parsoid configuration (see this topic)

Linking with Parsoid
To get VisualEditor to talk to Parsoid, add the following code to your  to specify your Parsoid instance:

A single Parsoid server can handle multiple wikis. The Parsoid  setting identifies your wiki configuration to Parsoid. Whether you set  explicitly or optionally accept the default value, the value from   must match the value from Parsoid's. By default it is set to the hostname named by, but you can pick an arbitrary string. Older versions of Parsoid also used a unique "prefix" to identify the server; you may need to list that here as well.

Parsoid must have been configured to match, for example with the following in Parsoid's : If you are using Parsoid older than 0.6.0, you would use a line in Parsoid's  like: Again, the "domain" property is optional in the Parsoid configuration; it defaults to the hostname used in the  property if not specified. The "prefix" property can also be omitted unless you are running a very old version of Parsoid.

See Parsoid/Setup for more details.

Servers with multiple virtual sites
If Apache2 is configured with multiple virtual sites, Parsoid is (in standard configuration) only able to access the default site. To check for this problem, run  on the server.

If the response starts with: then you don't have the problem, but if it doesn't, you may need to configure a host alias that Parsoid can use:

Look at the apache2 configuration file for the virtual server hosting the wiki, near the top of the file there should be a line like: "" If the '*' is present, then the alias can be to localhost, if there is an IP address replacing the '*' then the alias must be to that IP address. In the same file add a line: ""

In the hosts file of the server (/etc/hosts on Ubuntu), add a route for my_wiki_alias, either for 127.0.0.1 (if the apache2 virtual server configuration had the '*' above, else to the IP address from the apache2 virtual server configuration.

Finally, in the Parsoid  file, find the   setting, and set it to:

Reload the network config, apache config, and Parsoid config, and retest the curl command above.

The same method works for multiple wikis hosted on multiple virtual servers on a host (use a different alias and add a  setting for each wiki).

Linking with Parsoid in private wikis
Try one of these three options:

Authentication Bypass for Parsoid, without forwarding cookies
An alternative to the approach above is explicitly giving read permissions to requests from the parsoid server. There are two suggested solutions:

Replace 127.0.0.1 in both example solutions with the IP address of the server that is running Parsoid. This should of course only be done if the Parsoid server is on a 'trusted' network.

The forwarding of cookies (and the enabling of  and the   property) can be avoided by adding a user (which may be called  ) to the wiki and then add the NetworkAuth extension to the wiki with the configuration in "LocalSettings.php" file: Where the IP address matches that of the Parsoid server and the user matches the one you added to the wiki.
 * 1) Using the NetworkAuth extension


 * 2) Bypass how permissions are set

After your settings for  add the following to your "LocalSettings.php": Where the IP address matches that of the Parsoid server. Solution as mentioned in: explicitly remove restrictions for Parsoid by IP address.

Parsoid over HTTPS
By default, Parsoid only supports HTTP connections. However, it's easy to provide HTTPS Parsoid by using Stunnel, a utility which offers SSL wrapping for arbitrary sockets. Most Unix distributions have 'stunnel' or 'stunnel4' package available from the repository. First install stunnel: sudo apt install stunnel Then you need a config file for stunnel. It resides under, so create it here with the editor you like, e.g. nano: sudo nano /etc/stunnel/parsoid.conf Give the file similar content like this:

First you define the path to the ssl-keys used for your server. Then you give the service a name you like in brackets. It is only to know what this config shall do and to separate different configs in the same file. After the key  you write the port number for the public incoming connection, which is ssl-ciphered. After the  key write the intern port number, to which stunnel should route the traffic from the accept-port, but without ssl. At this port your parsoid-server is listen. If you use the Parsoid/Developer Setup use port number 8000, otherwise 8142 is standard port.

If you are using Let's Encrypt, you can use the following (replacing ` ` with the primary URL you have the certificate for):

This example use its own subdomain for parsoid and secured it with letsencrypt.

The stunnel config-file is ready now, but you need two more things to activate the configuration:

First enable stunnel to work after reboot. Therefore change 'ENABLED' to 1 in the file sudo nano /etc/default/stunnel4

ENABLED=1

Second, if you dont want to reboot now, you have to start the service. For Ubuntu 14.x use sudo /etc/init.d/stunnel4 restart For Ubuntu 16.x the command changed to sudo systemctl restart stunnel4.service To test configuration you can check in your browser, if the parsoid-server is answering over the ssl-connection. (e.g. write in the adress-line of your browser: ' https://parsoid.mydomain.com:8143 '). If the answer is „Welcome to the Parsoid web service.“ then congratulation - you have successfull secured your parsoid installation. One step remaining: Once this is working, you have to use the appropriate URL (e.g. ' https://parsoid.mydomain.com:8143 ') in your MediaWiki configuration for VisualEditor. Note the change from http to https and the port-number you set under accept in stunnel-configuration-file.

If you do not like to create an extra subdomain for parsoid like here, you can also use an existing subdomain (e.g. [wiki] if it's listed in your  file and then the appropriate URL will become: https://wiki.mydomain.com:8143 ).

Setting up such a configuration allows you to avoid the security implications of transmitting parsoid cookies in cleartext.

Producing and installing SSL certificates is beyond the scope of this document. Read more about stunnel:
 * Howto setup an ssl-tunnel using stunnel on ubuntu (12.x, 14.x)
 * Howto encrypt traffic to redis with stunnel on ubuntu 16.04

Parsoid on Windows and other systems
It is particularly complicated and time consuming to set up VisualEditor with Parsoid in non-standard systems, like those running Windows or non-standard Linux - those difficulties might even prevent the successful installation of VisualEditor for some people on some platforms:
 * Grrrr Debian assumptions
 * Can not get VisualEditor extension for MediaWiki REL1 23 working on freshly installed system
 * etc.
 * etc.

Setting VisualEditor up on shared hosting
See VisualEditor/Installation on a shared host

Running Parsoid tests
To run all parser tests and mocha tests: The parser tests have quite a few options now which can be listed using.

To run tests on the PHP port:

Converting simple wikitext
You can convert simple wikitext snippets from the command line using the  script in the bin/ directory:

echo 'Foo' | node bin/parse.js

The parse script has a lot of options. gives you information about this.

(In Ubuntu 13 and 14,  has been renamed to  . There, either type   or create a symbolic link or equivalent.)