This extension
comes with MediaWiki 1.35and above. Thus you do not have to download it again. However, you still need to follow the other instructions provided.
The setup process for VisualEditor was simplified significantly with MediaWiki 1.35, when Parsoid was integrated into core MediaWiki. The following instructions assume the use of MW 1.35 or higher; if you are using an older version, please see
this old version of the page.
MediaWiki extensions manual 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. Database changes No License MIT License Download Download extensionGit
[?]:
The VisualEditor extension allows for editing pages as rich content. It is based around a JavaScript library, also called "VisualEditor", that can potentially be used outside of MediaWiki as well. This page covers instructions for installing and configuring the VisualEditor extension. For help on using it, see Help:VisualEditor/User guide . For information on the development of the extension and the library, see VisualEditor .
InstallationVisualEditor folder to your extensions/ directory.cd extensions/
git clone --recurse-submodules https://gerrit.wikimedia.org/r/mediawiki/extensions/VisualEditorwfLoadExtension( 'VisualEditor' );
If you downloaded the MediaWiki tarball, you do not need to download this extension.
If you are using GitNote:
REL1_39 branch (command: git clone -b REL1_39 https://gerrit.wikimedia.org/r/mediawiki/extensions/VisualEditor.git).git submodule update --init command is vital, as VisualEditor MediaWiki extension needs the core VisualEditor submodule to work. If you do not use this command, VisualEditor will fail to work.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.
Setting up VisualEditor Short URLs on ApacheIf you are using non-standard short URLs such as "https://wiki.example.org/Page_title" on Apache, you need to adapt the rewrite rules for the web server.
VisualEditor will display some broken links if the wiki is not configured with Short Urls. See T328337.
Enabling the write APIThe user groups who should be able to use VisualEditor must have access to the MediaWiki write API. $wgGroupPermissions needs to be set accordingly, e.g. for the user group named user this is done with:
$wgGroupPermissions['user']['writeapi'] = true;Linking with Parsoid
By default VisualEditor is automatically configured to talk to a Parsoid service running on the same host (and on the same port). You should not need to change this in most cases!
Some cases when you do need to change the URL of Parsoid:
If you need to do this, add the following code to your LocalSettings.php to specify the URL for your Parsoid instance:
$wgVirtualRestConfig['modules']['parsoid'] = array(
// URL to the Parsoid instance.
// You should change $wgServer to match the non-local host running Parsoid
// Note! This is a server to server URL (it must be valid within your VM/container)
// For a VM or docker this will probably be correct:
// 'url' => "http://localhost/rest.php",
'url' => $wgServer . $wgScriptPath . '/rest.php',
// Parsoid "domain", see below (optional, rarely needed)
// 'domain' => 'localhost',
);
Note that you do not need to the initialise the $wgVirtualRestConfig array anywhere in LocalSettings.
Parsoid's domain setting here must match the host portion of $wgServer on the host running the Parsoid service.
If you set $wgVirtualRestConfig['modules']['parsoid'] then you will also need to install Parsoid, either via wfLoadExtension (below) or manually 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 Parsoid § Development —at the very least add the following to your LocalSettings.php:
// For 1.36-alpha and when you changed `wgVirtualRestConfig`: wfLoadExtension( 'Parsoid', 'vendor/wikimedia/parsoid/extension.json' );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 <VirtualHost> section in /etc/apache2/sites-enabled/000-default.conf or similar):
AllowEncodedSlashes NoDecode
If you do not, then VisualEditor will complain that "Revision IDs returned by the server do not match" or simply "Error contacting the Parsoid/RESTBase server (HTTP 404)" when editing a page title containing a slash, for example a subpage. See T268953 and the apache documentation for more information.
If the Apache server happens to be behind a Nginx proxy then its proxy_pass stanza should make use of the $request_uri parameter (cf. discussion on StackOverflow).
The following optional configurations can be used:
// Optional: Set VisualEditor as the default editor for anonymous users // otherwise they will have to switch to VE $wgDefaultUserOptions['visualeditor-editor'] = "visualeditor"; // Optional: Don't allow users to disable it $wgHiddenPrefs[] = 'visualeditor-enable'; // Optional: Enable VisualEditor's experimental code features $wgDefaultUserOptions['visualeditor-enable-experimental'] = 1; // Activate ONLY the 2017 wikitext editor by default $wgDefaultUserOptions['visualeditor-autodisable'] = true; $wgDefaultUserOptions['visualeditor-newwikitext'] = 1;
Other extensions which load plugins for VE can be loaded before or after VE; the plugins should work either way.
Changing active namespacesBy default, VisualEditor is only enabled for the namespaces "Main", "User", "File" and "Category". 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.
// Enable for the meta namespace, disable for the "File" namespace and enable for the "Extra", the latter being a custom namespace
$wgVisualEditorAvailableNamespaces = [
'Project' => true,
'File' => false,
'Extra' => true
];
Switching between wikitext and visual editing
Since MediaWiki 1.40, VisualEditor provides lossless switching between wikitext and visual editing without RESTBase.
MediaWiki version:≤ 1.39
Warning: Do not install RESTBase on a private wiki! RESTBase currently cannot be configured to keep page content private but will make the content of all pages publicly accessible. More details: T88016VisualEditor 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.
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 switchingTo 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 LocalSettings.php:
$wgVisualEditorParsoidAutoConfig = false;
$wgVirtualRestConfig['modules']['restbase'] = [
'url' => "http://yourRESTBaseserver.com:7231",
'domain' => '{domain}',
'parsoidCompat' => false
];
$wgVisualEditorFullRestbaseURL = 'http://yourRESTBaseserver.com:7231/{domain}/';
where {domain} is the value of the host portion of $wgServer on the host running Parsoid. Make sure that the port you specify here (e.g. :7231) is the same port as you specified in the RESTBase configuration. Be careful to include the trailing slash on $wgVisualEditorFullRestbaseURL!
If you can't access RESTBase port (e.g.:7231), 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 sitesParsoid is served in production using
Extension:MediaWikiFarm. Running Parsoid on multiple virtual sites using other mechanisms is untested; the instructions below have not been tested.
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]/rest.php/v1/page/Main_Page' on the server, or run curl '[https://your-wiki-base-url]/rest.php/v1/page/Main_Page' 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:
<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.
Now set the hostname in $wgServer to protocol://my_wiki_alias on the host running VisualEditor (see Manual:$wgServer).
In a private wiki, you should do this:
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.
// 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. $wgVirtualRestConfig['modules']['parsoid']['forwardCookies'] = true;
If you do set any property in $wgVirtualRestConfig['modules']['parsoid'] you will have to manually install Parsoid or VisualEditor will not work!
For Parsoid/PHP, MediaWiki 1.35.x to 1.38.x using Apache you should try this
virtual host configuration. Starting with MW 1.39+ it should work out of the box with no extra Apache configuration.
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 1.36+:$wgVisualEditorEnableBetaFeature = true;<1.36: Beta Feature shown by default; disable using:
$wgHiddenPrefs[] = 'visualeditor-enable';
$wgDefaultUserOptions['visualeditor-autodisable'] = true;Enabled by default As in "Enabled for all to opt-out" plus:
$wgHiddenPrefs[] = 'visualeditor-enable';Wikitext mode
$wgVisualEditorEnableWikitextBetaFeature = true;
$wgVisualEditorEnableWikitext = true;
$wgVisualEditorEnableWikitext = true; $wgDefaultUserOptions['visualeditor-newwikitext'] = 1;As in "Enabled for all to opt-out" plus:
$wgHiddenPrefs[] = 'visualeditor-newwikitext';Single edit tab Not a supported configuration.
$wgVisualEditorUseSingleEditTab = true; $wgDefaultUserOptions['visualeditor-tabs'] = 'multi-tab';
$wgVisualEditorUseSingleEditTab = true;Default edit tab behaviour will be to remember the last editor, and open with the wikitext editor for first edit; if you want it to be the visual editor, also add:
$wgDefaultUserOptions['visualeditor-editor'] = 'visualeditor';As in "Enabled for all to opt-out" plus:
$wgHiddenPrefs[] = 'visualeditor-tabs';Visual diffs on history pages
$wgVisualEditorEnableDiffPageBetaFeature = true;Not a supported configuration. Not a supported configuration.
$wgVisualEditorEnableDiffPage = true;Complete list of configuration options
Each configuration option is shown without the $wgVisualEditor prefix for brevity; replace the '…' when using.
…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. Warning: When removing a module on a production site (e.g. Wikimedia), first remove it from this array, wait for the change to propagate, and only then remove the module code and module registration. Otherwise there may be a period of time during which VisualEditor depends on a module that no longer exists.
…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. Warning: When removing a module on a production site (e.g. Wikimedia), first remove it from this array, wait for the change to propagate, and only then remove the module code and module registration. Otherwise there may be a period of time during which VisualEditor depends on a module that no longer exists. …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 $wgDefaultUserOptions!
…ParsoidAutoConfig
trueSysadmins Enables auto-configuration of the bundled version of the Parsoid REST API. Set to
false if you have an unusual Parsoid configuration and want to manually configure it. …RestbaseURL
falseSysadmins 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
falseSysadmins 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
trueSysadmins Whether to allow switching from wikitext to visual editor even if doing so may cause dirty diffs. See § Switching between wikitext and visual editing.
…SerializationCacheTimeout
3600Sysadmins 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
trueSysadmins Whether to put a change tag on every edit made with VisualEditor.
…EnableWikitext
falseSysadmins Whether to enable the wikitext source mode inside VisualEditor.
…EnableDiffPage
falseSysadmins Whether to enable the visual diff function on the history special page.
…EnableDiffPageBetaFeature
falseSysadmins Whether to allow users to enable the visual diff function on the history special page as a beta feature.
…EnableVisualSectionEditing
mobileSysadmins Whether to allow users to enable the section editing.
…UseSingleEditTab
falseSysadmins Whether to use only one edit tab, switching back and forth, or add a dedicated VisualEditor edit tab next to the existing one.
…SingleEditTabSwitchTime
20160101000000Sysadmins 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 null, the default edit tab caption will be used; the 'visualeditor-ca-ve-edit' message is available for this.
'editsource' – i18n message key to use for the old edit tab; if null, the tab's caption will not be changed
'create' – i18n message key to use for the VisualEditor create tab; if null, the default create tab caption will be used; the 'visualeditor-ca-ve-create' message is available for this
'createsource' – i18n message key to use for the old create tab; if null, the tab's caption will not be changed
'editlocaldescriptionsource' – i18n message key to use for the old edit tab on pages for files in foreign repos; if null, tab's caption will not be changed
'createlocaldescriptionsource' – i18n message key to use for the old create tab on pages for files in foreign repos; if null, tab's caption will not be changed
'editsection' – i18n message key to use for the VisualEditor section edit link; if null, the default edit section link caption will be used
'editsectionsource' – i18n message key to use for the source section edit link; if null, the link's caption will not be changed
…AutoAccountEnable
falseSysadmins Whether to enable VisualEditor for every new account.
This allows you to keep the 'visualeditor-enable' preference disabled by default, but still have VisualEditor available for new logged-in users (by setting this to true).
…DisableForAnons
falseSysadmins Whether to disable VisualEditor for non-logged-in users
This allows you to enable the 'visualeditor-enable' preference by default, but still disable VisualEditor for logged-out users (by setting this to true).
…TransitionDefault
falseSysadmins 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
trueSysadmins Whether to show the "welcome to the beta" dialog the first time a user uses VisualEditor
…NewAccountEnableProportion
falseSysadmins running user analytics Whether to enable VisualEditor for a proportion (Egyptian fraction) of all new accounts based on userID.
…FeedbackTitle
falseSysadmins 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
falseSysadmins 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.
…BrowserUnsupportedList 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 ([[./]]) bug in Firefox 14 and below (T52720) which prevent wider availability.
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
falseVisualEditor developers Whether to enable the (currently experimental) Table Of Contents widget
…RebaserURL
falseVisualEditor developers URL to use to access the experimental rebaser technology. If false, the technology isn't loaded.
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"To enable the so-called "2017 wikitext editor", follow the instructions for Wikitext mode in the § Quick configuration guide.
It is also possible to enable wikitext syntax highlighting for this editor; to do this, you must install the CodeMirror extension.
Rich template formsExtension:TemplateData allows the addition of template information, making templates easier to insert with the VisualEditor
Citations can be improved by configuring the citation tool , and also by setting up Citoid .
HooksAs of 2023, Visual Editor sets around 10 JavaScript hooks and 3 PHP hooks that are listed at VisualEditor/Hooks.
TroubleshootingAllowEncodedSlashes NoDecode must be added in the VirtualHost section of the wiki (T268953)./rest.php/?$query_string block – see respective Manual:Short_URL#GuidesAllowEncodedSlashes NoDecode must be added in the VirtualHost section of the wiki (T261921).wfLoadExtension( 'Parsoid', 'vendor/wikimedia/parsoid/extension.json' );.$wgVirtualRestConfig['modules']['parsoid'] (see: #Linking with Parsoid).mediawiki package, and if the file rest.php is not in your installation path, you are probably missing some new symbolic links (eventually evaluate the command ln -s /var/lib/mediawiki/* . from the installation path to install only the missing ones. In this case, you can ignore the errors about links you aready have)//wiki.example.org), you might be encountering bug T299175.
$wgTmpDirectory (for example "/tmp") has not write permissions.<Directory "D:/Wiki/htdocs">
...
Allow from 127.0.0.1
Satisfy Any
</Directory>
$wgVirtualRestConfig['modules']['parsoid']['url'] is not set correctly
/usr/lib/parsoid/src/lib/config/ParsoidConfig.js so that ParsoidConfig.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.
api.php in Parsoid's localsettings.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' });".
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.3