Extension:VisualEditor
![]() Release status: beta |
|
---|---|
![]() |
|
Implementation | Page action , Extended syntax , Beta Feature , Skin |
Description | Allows for editing pages as rich content |
Author(s) | Alex Monk, Bartosz Dziewoński, C. Scott Ananian, Christian Williams, David Lynch, Ed Sanders, Inez Korczyński, James D. Forrester, Moriel Schottlender, Roan Kattouw, Rob Moen, Subramanya Sastry, Thalia Chan, Timo Tijhof, Trevor Parscal, ... |
Latest version | continuous updates |
Compatibility policy | Snapshots releases along with MediaWiki. Master is not backward compatible. |
MediaWiki | 1.43-alpha |
Database changes | No |
License | MIT License |
Download | README |
|
|
|
|
Quarterly downloads | 845 (Ranked 3rd) |
Public wikis using | 7,436 (Ranked 19th) |
Translate the VisualEditor extension | |
Vagrant role | visualeditor |
Issues | Open tasks · Report a bug |
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 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/mediawiki/extensions/VisualEditor.git cd VisualEditor git submodule update --init
Note:
- 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 1.39; for that, use the
REL1_39
branch (command:git clone -b REL1_39 https://gerrit.wikimedia.org/r/mediawiki/extensions/VisualEditor.git
). - The
git submodule update --init
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.
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.
Skin compatibility
VisualEditor is known to be compatible with the following skins:
- Vector
- MonoBook
- Apex
- Poncho
- Minerva Neue
- Minerva (was part of MobileFrontend)
- Modern 1.35+
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.
Setting up VisualEditor
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.
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.
Parsoid → MediaWiki ↓ |
0.4.1 | 0.6.0 | 0.6.1 | 0.7.0 | 0.7.1 | 0.8.0 | 0.9.0 compat |
0.9.0 | 0.9.0+ | 0.10.0 | 0.11.0 |
---|---|---|---|---|---|---|---|---|---|---|---|
1.34 | X | X | |||||||||
1.33 | X | X | |||||||||
1.32 | |||||||||||
1.31 | - (d) | - (d) | X | X | X | X | X | X | — | — | |
1.30 | - (d) | - (d) | X | X | X | X | - (b) | - (b) | |||
1.29 | X | X | X | X | X | X | - (b) | - (b) | |||
1.28 | X | X | X | X | X | X | - (b) | - (b) | |||
1.27 | X | X | X | X | X | - | - (b) | - (b) | |||
1.26 | X | X | X | X | X | - (c) | - (c) | - | |||
1.25 | - (a) | - | |||||||||
1.24 | - | ||||||||||
1.23 | - |
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)
Node.js and Parsoid compatibility Matrix
Parsoid → Node.js↓ |
0.4.1 | 0.6.0 | 0.6.1 | 0.7.0 | 0.7.1 | 0.8.0 | 0.8.1 | 0.9.0 | 0.10.0 | 0.11.0 |
---|---|---|---|---|---|---|---|---|---|---|
12 | ||||||||||
10 | X | X | ||||||||
8 | ||||||||||
6+ | X |
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 LocalSettings.php
after you have downloaded the extension:
wfLoadExtension( 'VisualEditor' );
// Enable by default for everybody
$wgDefaultUserOptions['visualeditor-enable'] = 1;
// Optional: Set VisualEditor as the default for anonymous users
// otherwise they will have to switch to VE
// $wgDefaultUserOptions['visualeditor-editor'] = "visualeditor";
// Don't allow users to disable it
$wgHiddenPrefs[] = 'visualeditor-enable';
// OPTIONAL: Enable VisualEditor's experimental code features
#$wgDefaultUserOptions['visualeditor-enable-experimental'] = 1;
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 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")
$wgVisualEditorAvailableNamespaces = [
"File" => false
];
- Adding a namespace (e.g. "Help" and "Extra" which is an custom one)
$wgVisualEditorAvailableNamespaces = [
"Help" => true,
"Extra" => true
];
- Adding and removing a namespace (e.g. "File" and "Extra" which is an custom one)
$wgVisualEditorAvailableNamespaces = [
"File" => false,
"Extra" => true
];
Linking with Parsoid
To get VisualEditor to talk to Parsoid, add the following code to your LocalSettings.php
to specify your Parsoid instance:
$wgVirtualRestConfig['modules']['parsoid'] = array(
// URL to the Parsoid instance
// Use port 8142 if you use the Debian package
'url' => 'http://localhost:8000',
// Parsoid "domain", see below (optional)
'domain' => 'localhost',
// Parsoid "prefix", see below (optional)
'prefix' => 'localhost'
);
A single Parsoid server can handle multiple wikis. The Parsoid domain
setting identifies your wiki configuration to Parsoid. Whether you set domain
explicitly or optionally accept the default value, the value from $wgVirtualRestConfig
must match the value from Parsoid's config.yaml
. By default it is set to the hostname named by $wgCanonicalServer
, 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 config.yaml
:
mwApis:
- # This is the only required parameter,
# the URL of you MediaWiki API endpoint.
uri: 'http://path/to/my/wiki/api.php'
domain: 'localhost'
- # and another MediaWiki
uri: 'http://path/to/my/otherwiki/api.php'
domain: 'uniqueidentifier'
If you are using Parsoid older than 0.6.0, you would use a line in Parsoid's localsettings.js
like:
parsoidConfig.setMwApi({ uri: 'http://path/to/my/wiki/api.php', domain: 'localhost', prefix: 'localhost' });
Again, the "domain" property is optional in the Parsoid configuration; it defaults to the hostname used in the uri
property if not specified. The "prefix" property can also be omitted unless you are running a very old version of Parsoid.
See Parsoid/Setup#Configuration for more details.
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 $wgVisualEditorAllowLossySwitching=false
.
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.[1]
RESTBase setup for switching
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 config.yaml
described in the RESTBase configuration section.
Once the RESTBase server is operational, add the following code to your LocalSettings.php
:
$wgVirtualRestConfig['modules']['restbase'] = [
'url' => "http://yourRESTBaseserver.com:7231",
'domain' => '{domain}',
'parsoidCompat' => false
];
$wgVisualEditorFullRestbaseURL = 'http://yourRESTBaseserver.com:7231/{domain}/';
where {domain}
is the value of 'domain'
you specified in your Parsoid configuration file (you should change it in the configuration). Make sure that the port you specify here (e.g. :7231
) is the same port as you specified in the RESTBase configuration.
If you can't access RESTBase port(e.g.:7231
), 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 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 curl '[http://your-wiki-base-url]/api.php'
on the server.
If the response starts with:
<!DOCTYPE html><html lang="en-GB" dir="ltr" class="client-nojs"><head><meta charset="UTF-8" /><title>MediaWiki API help - ['''''Name of your wiki''''']</title>
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:
<VirtualHost *:80>
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:
ServerAlias my_wiki_alias
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 localsettings.js
file, find the parsoidConfig.setMwApi
setting, and set it to:
parsoidConfig.setMwApi({
uri: 'http://my_wiki_alias:80/path-to-my-wiki/api.php',
domain: '/* my Parsoid "domain" matching the value in LocalSettings.php */',
prefix: '/* my Parsoid "prefix" matching the value in LocalSettings.php */'
});
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 parsoidConfig.setMwApi
setting for each wiki).
Linking with Parsoid in private wikis
Try one of these three options:
Forwarding cookies to Parsoid
// This feature requires a non-locking session store. The default session store will not work and
// will cause deadlocks (connection timeouts from Parsoid) when trying to use this feature. Only required for MediaWiki 1.26.x and earlier!
$wgSessionsInObjectCache = true;
// Forward users' Cookie: headers to Parsoid. Required for private wikis (login required to read).
// If the wiki is not private (i.e. $wgGroupPermissions['*']['read'] is true) this configuration
// variable will be ignored.
//
// WARNING: ONLY enable this on private wikis and ONLY IF you understand the SECURITY IMPLICATIONS
// of sending Cookie headers to Parsoid over HTTP. For security reasons, it is strongly recommended
// that $wgVirtualRestConfig['modules']['parsoid']['url'] be pointed to localhost if this setting is enabled.
$wgVirtualRestConfig['modules']['parsoid']['forwardCookies'] = true;
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:
Note: 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.
- 1) Using the NetworkAuth extension
The forwarding of cookies (and the enabling of $wgSessionsInObjectCache
and the forwardCookies
property) can be avoided by adding a user (which may be called parsoid
) to the wiki and then add the NetworkAuth extension to the wiki with the configuration in "LocalSettings.php" file:
require_once "$IP/extensions/NetworkAuth/NetworkAuth.php";
$wgNetworkAuthUsers[] = [
'iprange' => [ '127.0.0.1' ],
'user' => 'parsoid'
];
Where the IP address matches that of the Parsoid server and the user matches the one you added to the wiki.
- 2) Bypass how permissions are set
After your settings for $wgGroupPermissions
add the following to your "LocalSettings.php":
if ( !isset( $_SERVER['REMOTE_ADDR'] ) OR $_SERVER['REMOTE_ADDR'] == '127.0.0.1' ) {
$wgGroupPermissions['*']['read'] = true;
$wgGroupPermissions['*']['edit'] = true;
}
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 /etc/stunnel/*.conf
, 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:
cert = /etc/ssl/my_certs/parsoid.crt
key = /etc/ssl/my_keys/mykey.key
CAfile = /etc/ssl/my_ca/ca.crt
[parsoid]
accept = 8143
connect = 8142
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 accept
you write the port number for the public incoming connection, which is ssl-ciphered.
After the connect
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 `<domain>` with the primary URL you have the certificate for):
cert = /etc/letsencrypt/live/<domain>/fullchain.pem
key = /etc/letsencrypt/live/<domain>/privkey.pem
[parsoid]
accept = 8143
connect = 8142
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 /etc/default/stunnel4
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 .crt
file and then the appropriate URL will become: https://wiki.mydomain.com:8143).
- You cannot use this type of configuration with Parsoid accessible via 'localhost', because the certificate chain for localhost, which will almost certainly be self-signed, will fail validation. You must use a proper hostname for Parsoid server, with appropriately issued and signed SSL certificate.
- You might enable SSL tunnels for stunnel. See e.g. for Debian /etc/default/stunnel4
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
- task T68519
- etc.
Setting VisualEditor up on shared hosting
See VisualEditor/Installation on a shared host
Quick configuration guide
Feature | Beta Features opt-in state | Enabled for all to opt-in | Enabled for all to opt-out | Enabled for all without opt-out |
---|---|---|---|---|
Visual mode | Out-of-the box. | $wgDefaultUserOptions['visualeditor-autodisable'] = true;
|
$wgDefaultUserOptions['visualeditor-enable'] = 1;
|
$wgDefaultUserOptions['visualeditor-enable'] = 1;
$wgHiddenPrefs[] = 'visualeditor-enable';
|
Wikitext mode | $wgVisualEditorEnableWikitextBetaFeature = true;
|
$wgVisualEditorEnableWikitext = true;
|
$wgVisualEditorEnableWikitext = true;
$wgDefaultUserOptions['visualeditor-newwikitext'] = 1;
|
$wgVisualEditorEnableWikitext = true;
$wgDefaultUserOptions['visualeditor-newwikitext'] = 1;
$wgHiddenPrefs[] = 'visualeditor-newwikitext';
|
Single edit tab | Not a supported configuration. | $wgVisualEditorUseSingleEditTab = true;
$wgDefaultUserOptions['visualeditor-tabs'] = 'multi-tab';
|
$wgVisualEditorUseSingleEditTab = true;
$wgDefaultUserOptions['visualeditor-editor'] = "visualeditor";
|
$wgVisualEditorUseSingleEditTab = true;
$wgDefaultUserOptions['visualeditor-editor'] = "visualeditor";
$wgHiddenPrefs[] = 'visualeditor-tabs';
|
Visual diffs on history pages | $wgVisualEditorEnableDiffPageBetaFeature = true;
|
Configuration not currently supported. | Configuration not currently supported. | $wgVisualEditorEnableDiffPage = true;
|
Complete list of configuration options
Each configuration option is shown without the $wgVisualEditor
prefix for brevity; replace the '…' when using.
Option | Default value | Useful for… | Documentation |
---|---|---|---|
…PluginModules
|
[]
|
Extension developers | Array of ResourceLoader module names (strings) that should be loaded when VisualEditor is loaded. Other extensions that extend VisualEditor should add to this array. |
…PreloadModules
|
[
"site",
"user"
]
|
Extension developers | Array of ResourceLoader module names (strings) that should be loaded before VisualEditor is loaded. Other extensions that extend VisualEditor and need to set up their environment before loading should add to this array. |
…PreferenceModules
|
{
"visualeditor-enable-experimental": "ext.visualEditor.experimental"
}
|
Extension developers | Associative array of ResourceLoader module names (strings) that should be loaded when VisualEditor is loaded if the current user has a preference set. Other extensions that extend VisualEditor should add to this array if they want their addition to be opt-in or opt-out. Keys are preference names, values are ResourceLoader module names.
Remember to also set defaults in |
…RestbaseURL
|
false
|
Sysadmins | URL to use to access the main RESTbase call. The page name will be appended directly to this value, so this needs to be set to something like 'https://en.wikipedia.org/api/rest_v1/page/html/ ' including the trailing slash.
If this is set, the page HTML will be requested from RESTbase. If this is not set, the page HTML will be requested from the API, which will send an HTTP request to Parsoid or to RESTbase if available. |
…FullRestbaseURL
|
false
|
Sysadmins | URL to use to access the rest of RESTbase. The page name will be appended directly to this value, so this needs to be set to something like 'https://en.wikipedia.org/api/rest_ ' excluding the trailing slash.
|
…AllowLossySwitching
|
true
|
Sysadmins | Whether to allow switching from wikitext to visual editor even if doing so may cause dirty diffs. See #Switching between Wikitext Editing and VisualEditor. |
…SerializationCacheTimeout
|
3600
|
Sysadmins | Serialization cache timeout, in seconds |
…AvailableNamespaces
|
[
"User" => true,
"File" => true,
"Category" => true,
"_merge_strategy" => "array_plus"
]
|
Sysadmins | Namespaces in which to enable VisualEditor (mapped from namespace canonical name to a boolean flag), on top of $wgContentNamespaces .
|
…AvailableContentModels
|
[
"wikitext" => "article",
"_merge_strategy" => "array_plus"
]
|
Extension developers | Content models in which to enable VisualEditor (mapped from content model name to a boolean flag). |
…UseChangeTagging
|
true
|
Sysadmins | Whether to put a change tag on every edit made with VisualEditor. |
…EnableWikitext
|
false
|
Sysadmins | Whether to enable the wikitext source mode inside VisualEditor. |
…EnableDiffPage
|
false
|
Sysadmins | Whether to enable the visual diff function on the history special page. |
…EnableDiffPageBetaFeature
|
false
|
Sysadmins | Whether to allow users to enable the visual diff function on the history special page as a beta feature. |
…EnableVisualSectionEditing
|
false
|
Sysadmins | Whether to allow users to enable the section editing. |
…UseSingleEditTab
|
false
|
Sysadmins | Whether to use only one edit tab, switching back and forth, or add a dedicated VisualEditor edit tab next to the existing one. |
…SingleEditTabSwitchTime
|
20160101000000
|
Sysadmins | From what timestamp to warn existing editors that the installation has switched from two edit tabs to one. In general you should ignore this. |
…TabPosition
|
'before'
|
Sysadmins | If showing two edit tabs, where to put the VisualEditor edit tab in relation to the system (or WikiEditor) one:
|
…TabMessages
|
{
"edit": null,
"editsource": "visualeditor-ca-editsource",
"create": null,
"createsource": "visualeditor-ca-createsource",
"editlocaldescriptionsource": "visualeditor-ca-editlocaldescriptionsource",
"createlocaldescriptionsource": "visualeditor-ca-createlocaldescriptionsource",
"editsection": null,
"editsectionsource": "visualeditor-ca-editsource-section"
}
|
Sysadmins | Configuration of what messages to use for the various kinds of edit tab users can see, if showing two edit tabs:
'edit' – i18n message key to use for the VisualEditor edit tab; if 'editsource' – i18n message key to use for the old edit tab; if 'create' – i18n message key to use for the VisualEditor create tab; if 'createsource' – i18n message key to use for the old create tab; if 'editlocaldescriptionsource' – i18n message key to use for the old edit tab on pages for files in foreign repos; if 'createlocaldescriptionsource' – i18n message key to use for the old create tab on pages for files in foreign repos; if 'editsection' – i18n message key to use for the VisualEditor section edit link; if 'editsectionsource' – i18n message key to use for the source section edit link; if |
…AutoAccountEnable
|
false
|
Sysadmins | Whether to enable VisualEditor for every new account.
This allows you to keep the ' |
…DisableForAnons
|
false
|
Sysadmins | Whether to disable VisualEditor for non-logged-in users
This allows you to enable the ' |
…TransitionDefault
|
false
|
Sysadmins | For wikis planning to use the 'visualeditor-betatempdisable ' preference to auto-opt-out existing users whilst enabling by default for all existing users, whether to start recording explicit opt-outs against implicit ones.
|
…ShowBetaWelcome
|
true
|
Sysadmins | Whether to show the "welcome to the beta" dialog the first time a user uses VisualEditor |
…NewAccountEnableProportion
|
false
|
Sysadmins running user analytics | Whether to enable VisualEditor for a proportion (Egyptian fraction) of all new accounts based on userID. |
…FeedbackTitle
|
false
|
Sysadmins | Whether to enable the MediaWiki feedback tool inside the help menu of VisualEditor. If enabled, the title of the page at which to point the MediaWiki feedback tool. |
…FeedbackAPIURL
|
false
|
Sysadmins | If set, the API of the remote wiki at which to point the MediaWiki feedback tool. |
…SkinToolbarScrollOffset
|
[]
|
Skin developers | An array of skin names mapped to pixel values to which to set the toolbar scroll offsets. |
…BrowserBlacklist
|
{
"firefox": [
[
"<=",
11
]
],
"safari": [
[
"<=",
6
]
],
"opera": [
[
"<",
12
]
],
"msie": [
[
"<",
10
]
]
}
|
VisualEditor developers | List of browsers with which VisualEditor is incompatible. See jquery.Client for specification. If the user's browser is matched, VisualEditor will refuse to load.
Firefox – There is a wikilink corruption ( Safari – Older versions of Safari suffered from corruption issues from various old browser plugins. Opera – Below version 12, Opera was untested, and as its user base is almost non-existent anyway it's blocked. Internet Explorer – At or below version 9, there are various incompatibilities in layout and feature support. Versions 10 and 11 should work correctly. Not listed independently, because it's inherited from MediaWiki itself, Android at 3.x and below "support" CE but don't trigger keyboard input or have other issues, making it useless for users. |
…EnableTocWidget
|
false
|
VisualEditor developers | Whether to enable the (currently experimental) Table Of Contents widget |
…RebaserURL
|
false
|
VisualEditor developers | URL to use to access the experimental rebaser technology. If false, the technology isn't loaded. |
Old configuration parameters
As above, each configuration option is shown without the $wgVisualEditor
prefix for brevity.
Option | MW versions | Default value | Documentation |
---|---|---|---|
…Namespaces
|
1.22–1.25 |
|
List of namespaces IDs where is the VisualEditor is activated.
This parameter has been essentially replaced by |
…SupportedSkins
|
1.22–1.28 | [
"vector",
"apex",
"monobook",
"minerva",
"blueprint"
]
|
List of skins VisualEditor integration supports. If the user's skin is not matched, VisualEditor will refuse to load.
This is replaced by a dynamical check of the requirements (T161373). |
Related configuration parameters
See also Upload dialog#Configuration (for wiki sysadmins) 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:
$wgVisualEditorEnableWikitext = true;
$wgDefaultUserOptions['visualeditor-newwikitext'] = 1;
$wgHiddenPrefs[] = 'visualeditor-newwikitext';
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:
$wgVisualEditorEnableWikitext = true;
- Enabling wikitext syntax highlighting
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.
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.
<Directory "D:/Wiki/htdocs"> ... Allow from 127.0.0.1 Satisfy Any </Directory>
- parsoidserver-http-curl-error: couldn't connect to host.
- Parsoid is not running, or
$wgVirtualRestConfig['modules']['parsoid']['url']
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
api.php
in Parsoid'slocalsettings.js
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
/usr/lib/parsoid/src/lib/config/ParsoidConfig.js
so thatParsoidConfig.prototype.strictAcceptCheck = false;
. 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.
References
See also
- Extension:ParsoidBatchAPI: If your pages are somewhat complex, you absoultely want to install this extension for parsoid to not bring your server down.
![]() | This extension is being used on one or more Wikimedia projects. This probably means that the extension is stable and works well enough to be used by such high-traffic websites. Look for this extension's name in Wikimedia's CommonSettings.php and InitialiseSettings.php configuration files to see where it's installed. A full list of the extensions installed on a particular wiki can be seen on the wiki's Special:Version page. |
![]() | VisualEditor is maintained by Editing team.
Get help:
|
- Extensions bundled with MediaWiki 1.35
- Beta status extensions
- Page action extensions
- Extended syntax extensions
- Beta Feature extensions
- Skin extensions
- MIT licensed extensions
- Extensions in Wikimedia version control
- BeforeInitialize extensions
- BeforePageDisplay extensions
- ChangeTagsListActive extensions
- CustomEditor extensions
- DifferenceEngineViewHeader extensions
- EditPage::showEditForm:fields extensions
- GetBetaFeaturePreferences extensions
- GetPreferences extensions
- ListDefinedTags extensions
- MakeGlobalVariablesScript extensions
- OutputPageBodyAttributes extensions
- ParserTestGlobals extensions
- PreferencesFormPreSave extensions
- RecentChange save extensions
- RedirectSpecialArticleRedirectParams extensions
- ResourceLoaderGetConfigVars extensions
- ResourceLoaderRegisterModules extensions
- SkinEditSectionLinks extensions
- SkinTemplateNavigation::Universal extensions
- TextSlotDiffRendererTablePrefix extensions
- UserLoggedIn extensions
- All extensions
- Extensions used on Wikimedia
- WYSIWYG extensions
- VisualEditor