Extension:VisualEditor/en

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 parser service that needed to be installed and enabled in order to edit pages with it; this is now bundled with MediaWiki core. For documentation specific to this old Parsoid service, see this old version of the page.

User guide
See.

For the general user
If you're using the latest stable version of MediaWiki, you will not need to download the VisualEditor extension from Special:ExtensionDistributor/VisualEditor as it already comes with the MediaWiki tarball.

If you are using Git
The following download instructions are for use with the latest nightly build of MediaWiki only.

Installation
VisualEditor needs to be installed with:

Skin compatibility
VisualEditor is known to be compatible with the following skins:


 * Minerva (was part of )
 * Minerva (was part of )
 * Minerva (was part of )
 * Minerva (was part of )
 * Minerva (was part of )
 * Minerva (was part of )
 * Minerva (was part of )

Other skins are not officially supported, but it should be compatible with any skin that uses the required HTML structure See . 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.

Installing Parsoid
Before MediaWiki 1.35, it was necessary to set up the Node.js service before you could edit or save pages; see  for documentation. This is not necessary for MediaWiki 1.35 and later, unless you are running a pre-release version of VisualEditor from git (see notes above).

Basic configuration for VisualEditor
Basic operation of VisualEditor in MediaWiki 1.35 and later does not require any manual configuration.

For users of earlier versions, or those with special needs, the following are the most-frequent customizations.

Short URLs on Apache (MW ≥ 1.35.x)
If you are using VisualEditor for MediaWiki 1.35 and later with non-standard short URLs as "https://wiki.example.org/Page_title" on Apache you need to adapt the rewrite rules of the webserver.

Enabling the write API
The user groups who should be able to use VisualEditor must have access to the MediaWiki write API. needs to be set accordingly, e.g. for the user group named user this is done with:

Linking with Parsoid
By default, VisualEditor is automatically configured to talk to a Parsoid service running on the same host. You should not need to change this in most cases! Advanced configurations may wish to run Parsoid on a dedicated host or cluster. If you need to do this, add the following code to your  to specify your non-local Parsoid instance:

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

If you set, then you will also need to manually install Parsoid. Either on a separate server or via the developer instructions on the Parsoid page.

Note for developers: as noted above, in development releases including 1.36-alpha Parsoid will need to be manually loaded. This will change before 1.36 is released. If you are running a development release, you should follow the instructions in  at the very least add the following to your :

Allowing VisualEditor on page titles containing slashes
If you are serving MediaWiki from apache2, you will need to add the following to your top level server configuration (often a  section in   or similar):

If you do not, then VisualEditor will complain that "" or simply "" when editing a page title containing a slash, for example a subpage. See 268953 and the Apache documentation for more information.

If the Apache server happens to be behind a Nginx proxy, then its  stanza should make use of the  parameter (cf. discussion on StackOverflow).

Activating VisualEditor by default
Before MediaWiki 1.35, VisualEditor did not enable itself for users by default. To make it available, add the following lines to your wiki's  after you have downloaded the extension. This is not necessary for MediaWiki 1.35 and later.

The following optional configurations can also be used:

Other extensions which load plugins for VisualEditor 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
By default, VisualEditor is only enabled for the namespaces "   ", "    ", "    " and "    ". It is however possible to add or remove namespace using the English language canonical names defined for the respective namespaces such as e.g. "Project", "Talk", etc. Additional custom namespaces use the names used to create them.

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

However, without a 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.

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 "" or ""; 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 work around 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 VisualEditor 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, or run   ensuring the URL matches the SSL certificate used 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 ( on Ubuntu), add a route for , either for   (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
In a private wiki, you should do this:

Forwarding cookies to Parsoid
This is the default configuration for VisualEditor if not everyone is allowed to read every page, as such the below should not be required in most cases.

If you do set any property in, you will have to manually install Parsoid or VisualEditor will not work!

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 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, follow the instructions for wikitext mode in the Quick configuration guide.

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

Rich template forms
allows the addition of template information, making templates easier to insert with the VisualEditor.

Improved citation tool
Citations can be improved by configuring the citation tool, and also by setting up.

Troubleshooting

 * All templates appear as puzzle icons instead of displaying its contents
 * See Topic:V6tbh7vonvg3mzl9.


 * Docker :
 * Ensure that the MediaWiki container name does not equal to the domain the wiki is running on. If both names are equal, the api will try to connect to the domain the wiki is running on, but only receive the local ip of the container. This will cause errors when  is enabled.


 * }
 * When editing subpages on Apache,  must be added in the VirtualHost section of the wiki (268953).
 * On a private wiki, see "parsoidserver-http-bad-status : 401" below.


 * An unresolved error for some users (Topic:Wc5hugtg7besmcb2).
 * An unresolved error for some users (Topic:Wc5hugtg7besmcb2).


 * Caused by the 'writeapi' right being revoked (or not granted). Check your  and remove any overrides for this right. (265043)
 * Caused by the 'writeapi' right being revoked (or not granted). Check your  and remove any overrides for this right. (265043)


 * Possible reasons for this problem:
 * Caused by ModSecurity (or possibly another WAF). Request your hosting service provider to whitelist the security rules that were being triggered by your site.
 * When the web server is Apache,  must be added in the VirtualHost section of the wiki (261921).
 * Possibly Parsoid is not loaded when using default configuration (local Parsoid, no RestBase). Add to :.
 * Caused by VisualEditor for MW 1.35 and later due to insufficient rewrite rules in case of non-standard short URLs (T270376). See webserver for the solution.
 * Caused by VisualEditor for MW 1.35 and later due to insufficient rewrite rules in case of non-standard short URLs (T270376). See webserver for the solution.


 * If you're running a private wiki, you might be encountering bug (268277).
 * If you're running a private wiki, you might be encountering bug (268277).


 * Error contacting the Parsoid/RESTBase server (HTTP 500) when saving page with accented character in title, on Windows/IIS
 * IIS expects URLs to be encoded using legacy single-byte encodings, but MediaWiki uses UTF-8. Follow these instructions to resolve this: https://support.microsoft.com/en-us/help/2277918/fix-a-php-application-that-depends-on-the-request-uri-server-variable (269673)


 * Error contacting the Parsoid/RESTBase server (HTTP 500) when trying to edit an existing page with VisualEditor
 * Persisting in MW 1.35.x. See 270377.


 * 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 directory  (for example "/tmp") has not write permissions.
 * 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.
 * 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.


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


 * parsoidserver-http-bad-status : 401
 * Caused by read or edit restrictions (aka private wiki). 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 (See Topic:Vv35plp6g16qno0s and the ticket: MW 1.35.0 "Error contacting the Parsoid/RESTBase server: http-bad-status" on a private wiki).


 * 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-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.


 * 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 ' });".

Development documentation

 * - non formal guide for hacking VisualEditor. Includes code snippets and other information useful to gadget authors (and other custom JS developers).
 * API Documentation - information on some VisualEditor JS classes.