Extension:VisualEditor

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.

Before MediaWiki 1.35, the VisualEditor extension relied on a separate Parsoid parser service that needed 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 not need to download the VisualEditor-MediaWiki extension from the ExtensionDistributor page as it already comes with the MediaWiki tarball.

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/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 and will not work with the older, official releases of MediaWiki like ; 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.
 * See Parsoid for details on linking an alpha build of the Parsoid library up to VisualEditor; the latest version of VisualEditor may need a development version of Parsoid as well.
 * It is recommended to use PHP 7.3 or later, as Parsoid uses less memory on newer versions of PHP. This is not a hard requirement; WMF still runs PHP 7.2 in production.

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
 * Poncho
 * Minerva Neue
 * Minerva (was part of MobileFrontend)
 * Modern

Setting up VisualEditor
Before MediaWiki 1.35 it was necessary to set up the Parsoid Node.js service before you could edit or save pages. See Parsoid/JS for documentation. This is not necessary for MediaWiki 1.35 and later.

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:

Other extensions which load plugins for VE 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
By default VisualEditor is automatically configured to talk to a Parsoid service running on the same host. Advanced configurations may wish to run Parsoid on a dedicated host or cluster. To do this, add the following code to your  to specify your Parsoid instance:

Parsoid's  setting must match the host portion of   on the host running the Parsoid service.

Switching between Wikitext Editing and VisualEditor
VisualEditor allows you to switch back and forth between wikitext and visual editing.

However, without a RESTBase server, switching from wikitext to visual editing may result in dirty diffs when saving (non-semantic whitespace changes to wikitext formatting). If you want the ability to switch between wikitext editing and VisualEditor and save your changes without dirty diffs, you must install a RESTBase server. (Prior to T214542, switching without RESTBase was not possible at all.)

If you can't set up RESTBase and dirty diffs are undesirable on your wiki (e.g. your users carefully review all changes), you can disable this feature using.

When switching isn't possible and 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.

RESTBase setup for switching
To set up your own RESTBase service follow the RESTBase installation instructions, paying special attention to the Parsoid configuration.

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

where  is the value of the host portion of   on the host running Parsoid. Make sure that the port you specify here (e.g. ) is the same port as you specified in the RESTBase configuration. Be careful to include the trailing slash on !

If you can't access RESTBase port (e.g. ), you can workaround the problem using an httpd proxy; refer to "if RESTBase port is blocked". If your wiki is served through HTTPS, RESTBase must also be served through HTTPS; else users could experience "mixed-content" errors and the switch from wikitext to VisualEditor would not work.

Now when you make changes in a wikitext editor, you can switch to visual editor without causing dirty diffs.

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 contains the main page of your wiki 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.

Now set the hostname in  to   on the host running VisualEditor.

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

Forwarding cookies to Parsoid
This is the default configuration for VisualEditor if not everyone is allowed to read every page.

Complete list of configuration options
Each configuration option is shown without the  prefix for brevity; replace the '…' when using.

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

Related configuration parameters
See also Upload dialog for information about configuring the drag-and-drop/copy&paste functionality for uploading media files through VisualEditor.

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

Expanding visual editor

 * Extension:TemplateData - allows the addition of template information, making templates easier to insert with the VisualEditor
 * VisualEditor/Citation tool - guide on improving the cite tool

Troubleshooting

 * Error loading data from server : HTTP 500. Would you like to retry?
 * Possible reasons for this problem:
 * On new installs, "curl", "php5-curl", or "php7.0-curl" (or other package appropriate to your PHP version) is not installed on the server.
 * setMwApi uri is set incorrectly with e.g. https instead of http.
 * Bad rewrite rules in the apache configuration that would cause API failures.
 * The SSL/TLS certificates are expired.
 * When 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
 * 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 ' });".


 * parsoidserver-http-not-acceptable : 406
 * Caused by Parsoid 0.9 enforcing clients to return a 1.6.0 and greater HTML version string in the header. This most likely affects Debian users as they are using slightly older MediaWiki versions with MediaWiki's Parsoid APT repository. This can be fixed by either downgrading to 0.8 (not easy as 0.8 no longer exists in the repository) or by editing  so that  . The latter will be overwritten on any package upgrade, so it is up to the administrator to lock the package and keep on top of updates manually.


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


 * Error contacting the Parsoid/RESTBase server (HTTP 404) with Parsoid-PHP
 * When the web server is Apache, it must be added  in the VirtualHost section of the wiki (phabricator:T261921).