Extension:VisualEditor

i

The VisualEditor extension allows for editing pages as rich content. There is also a project of the same name aiming to create a reliable rich-text editor for the Web and for MediaWiki.

The VisualEditor extension relies on the separate nodeJS-based Parsoid parser service that needs to be installed and enabled in order to edit pages with it.

User guide
See Help:VisualEditor/User guide.

Download
For the General User: If you're using the latest stable version of MediaWiki you will need to download the VisualEditor-MediaWiki extension from the ExtensionDistributor page.

For the Advanced User:

The following download instructions are for use with the latest nightly build of MediaWiki only. cd extensions git clone https://gerrit.wikimedia.org/r/p/mediawiki/extensions/VisualEditor.git cd VisualEditor git submodule update --init

If you cannot use git (e.g. you are in an air-gapped installation), you can download a snapshot of VisualEditor-MediaWiki for master or for a release version of MediaWiki from the ExtensionDistributor page. After you've got the code, save it into the extensions/VisualEditor directory of your wiki.
 * VisualEditor-MediaWiki's master branch contains the latest code, as used at Wikimedia. This code is potentially slightly buggy or unstable, but is likely to have fewer bugs and more features than old builds.
 * The master branch requires alpha builds of MediaWiki (currently, 1.31-wmf.20 ) and will not work with the older, official releases of MediaWiki like 1.30.0; for that, use the  branch (command:  ).
 * The  command is vital, as MediaWiki-VisualEditor needs the core VisualEditor submodule to work. If you do not use this command, VisualEditor will fail to work.

Skin compatibility
VisualEditor is known to be compatible with the following skins: Other skins are not officially supported, but it should be compatible with any skin that uses the required HTML structure – see VisualEditor/Skin requirements. Some fiddling with skin stylesheets might be necessary to make everything look nice. It will load on any skin if it matches the feature detection.
 * Vector
 * MonoBook
 * Apex
 * Minerva (part of MobileFrontend)

Set up a Parsoid service
If you want to be able to edit existing pages and save pages with VisualEditor you need a Parsoid service that converts between wikitext and the HTML that VisualEditor displays for editing.

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.

Basic configuration for MediaWiki-VisualEditor
By default, MediaWiki-VisualEditor does not enable itself for users. To make it available, add the following lines to your wiki's  after you have downloaded the extension:

"Note that you can do this before you have installed the Parsoid node.js service to experiment with VE; this will mean that you can try the editor out in 'create' mode on your own wiki, but you will not be able to save or edit existing pages."Other extensions which load plugins for VE (e.g. Math) can be loaded before or after VE if you are using MediaWiki 1.25 or later; the plugins should work either way.

Changing active namespaces
Per default, the VisualEditor is only enabled for the namespaces "Main", "User", "File" and "Category". It is however possible to add or remove namespaces. There are many ways to do this but it is recommended to use the canonical names defined for the respective namespaces. Note that this is different to MediaWiki core and nearly all extensions.


 * Removing a namespace (e.g. "File")


 * Adding a namespace (e.g. "Help" and "Extra" which is an custom one)


 * Adding and removing a namespace (e.g. "File" and "Extra" which is an custom one)

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.

Switching between Wikitext Editing and VisualEditor
VisualEditor allows you to switch back and forth between wikitext editing and VisualEditor. However, without a RESTBase server, when you try to switch from a wikitext editing environment into VisualEditor, your only options are Cancel or Discard my changes and switch; any changes you made will be discarded if you switch. If you want the ability to switch between wikitext editing and VisualEditor and save your changes, you must install a RESTBase server.

To set up your own RESTBase service follow the RESTBase installation instructions. Note that if you were successful setting up the Parsoid service, setting up a RESTBase server is similar because it also runs under Node.js.

For VisualEditor you do not need the configuration section in  described in the RESTBase configuration section.

Once the RESTBase server is operational, add the following code to your :

where  is the value of   you specified in your Parsoid configuration file (you should change it in the configuration). Make sure that the port you specify here (e.g. ) is the same port as you specified in the RESTBase configuration.

If you can't access RESTBase port(e.g. ), you can bypass via httpd proxy. refer IF Restbase Port is blocked. If your wiki is served through HTTPS, RESTBase must be served through HTTPS; else users could experience "mixed-content" errors and the switch from wikitext to VisualEditor could not work.

Now when you make changes in a wikitext editor, you are presented with a dialog box with a Switch option instead of Discard my changes and switch.

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 la 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, 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 these three things:

Forwarding Cookies to Parsoid
'' ONLY enable this on private wikis and ONLY IF you understand the SECURITY IMPLICATIONS of sending Cookie headers to Parsoid over HTTP! (but see the HTTPS section below)''

Parsoid Authentication Without Forwarding Cookies
An alternative to the approach above is explicitely 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

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.
 * 2) Adapt how permissions are set

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. The following config file shard (e.g. /etc/stunnel/parsoid.conf) should do the trick:

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

Where [parsoid] is a new subdomain which is created. Once this is working, you can use the appropriate URL (e.g. 'https://parsoid.mydomain.com:8143') in your MediaWiki configuration for VisualEditor. You can 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.

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

Complete list of configuration options
Each configuration option is shown without the  prefix for brevity.

Old configuration parameters
As above, each configuration option is shown without the  prefix for brevity.

Integration of "2017 wikitext editor"
Since release branch "REL1_29" (MediaWiki 1.29 and later) it is also possible to activate the so called "2017 wikitext editor". To enable it and at the same time make it available to all users by default add the following to your "LocalSettings.php" file: If you want all users to have the 2017 wikitext editor available as a beta feature, i.e. leave the choice to the users, install the BetaFeatures extension add the following to your "LocalSettings.php" file:

It is also possible to enable wikitext syntax highlighting for the "2017 wikitext editor". To do this you have to additionally install the CodeMirror extension.
 * Enabling wikitext syntax highlighting

Troubleshooting

 * Error loading data from server : HTTP 500. Would you like to retry?
 * Usually for new installs, this is due to "curl", "php5-curl", or "php7.0-curl" not being installed on your server.
 * Or perhaps your setMwApi uri is set incorrectly with e.g. https instead of http. Or there is a bad rewrite rule in your apache configuration that would cause API failures.
 * If you are running Windows Authentication with Apache, you would need to white-list 127.0.0.1 in your Apache conf, as Apache doesn't have read access.
 * parsoidserver-http-curl-error : couldn't connect to host.
 * Parsoid is not running, or  is not set correctly


 * parsoidserver-http-curl-error : Failed to connect to .... : Permission denied.
 * Can be caused by a cURL request on a Security-Enhanced Linux (SELinux, like CentOS) to a non standard port like 8000 in the example configuration above, see http://www.akashif.co.uk/php/curl-error-7-failed-to-connect-to-permission-denied and https://www.centos.org/forums/viewtopic.php?f=47&t=53223&p=225372#p225372


 * parsoidserver-http-bad-status : 401
 * Caused by read or edit restrictions. If you've set up a private wiki and don't want to use cookie forwarding, you can explicitly remove restrictions for Parsoid by IP address.


 * parsoidserver-http-not-found : 404 (or timeout)
 * Caused by wrong path to MediaWiki API endpoint. Set correct url to the right path to  in Parsoid's   config file. If you have set up following the recommendations, your API path would be "http://localhost/w/api.php". Add this API path to "localsettings.js" like "parsoidConfig.setMwApi({uri: 'http://localhost/w/api.php ' });".


 * No visible error (Appears to load forever)
 * Check the parsoid log file, and consult Parsoid/Troubleshooting.