How to Enable and Configure VisualEditor for Collaborative Editing in MediaWiki

VisualEditor gives MediaWiki users a true WYSIWYG editing experience, letting them format pages without learning wikitext. It is bundled with MediaWiki 1.35 and later; the only real complexity is the Parsoid parser it talks to — which, since MediaWiki 1.42, is built into core and needs no separate installation. This guide covers installation, configuration and troubleshooting for current releases (1.42 through the 1.43 LTS and newer).

Prerequisites and compatibility

• MediaWiki 1.35+ ships VisualEditor in extensions/. On 1.42 and newer, Parsoid is part of core, so nothing else is required
• MediaWiki 1.35–1.41 — you additionally need a running Parsoid service (see below)
• TemplateData — bundled since 1.35 and enabled by default; without it, templates render as puzzle icons in the editor and the template dialog is unavailable
• PHP cURL is recommended for the HTTP client used by Parsoid

Installation

Because VisualEditor ships with the source tree, installation is just loading the extension at the bottom of LocalSettings.php:

wfLoadExtension( 'VisualEditor' );

Then confirm it appears under Special:Version. On MediaWiki 1.42+, that is the entire installation — Parsoid runs inside rest.php and requires no configuration. The REST API endpoint is https://your.wiki/rest.php/v1/; a quick smoke test is curl https://your.wiki/rest.php/v1/page/Main_Page, which should return JSON with the page HTML.

Parsoid on MediaWiki 1.35–1.41

Older releases need an external Parsoid instance. The classic configuration points it at the bundled service (installed via composer require wikimedia/parsoid or the mediawiki-services-parsoid container):

$wgVirtualRestConfig['modules']['parsoid'] = [
    'url' => "$wgServer$wgScriptPath/rest.php",
    'domain' => $wgServerHostName,
    'forwardCookies' => true, // required for private wikis
];

On private wikis, cookie forwarding lets Parsoid authorize reads on behalf of the logged-in user — make sure that connection runs over HTTPS, since the forwarded cookie authenticates the session. This entire section is unnecessary on 1.42+, which is the best reason to upgrade.

Editor defaults and tabs

By default MediaWiki shows two edit tabs: Edit (VisualEditor) and Edit source (wikitext). You can collapse them into a single tab that prefers one editor:

// One tab, defaulting to VisualEditor; or 'prefer-wt' for wikitext
$wgVisualEditorUseSingleEditTab = 'prefer-ve';

// Default both tab-style and editor for all accounts
$wgDefaultUserOptions['visualeditor-tabs'] = 'prefer-ve';
$wgDefaultUserOptions['visualeditor-editor'] = 'visualeditor';

To keep the two-tab layout but change which tab is shown first, use $wgVisualEditorTabPosition (default 'before', i.e. VisualEditor first). For anonymous users, $wgVisualEditorDisableForAnons keeps the classic tabs regardless of other settings — a deliberate choice on wikis where anonymous contributions are dominated by wikitext-power users.

The 2017 wikitext mode

VisualEditor can also serve as a modern wikitext editor inside the same interface — often called "2017 wikitext mode"— with syntax highlighting and visual preview:

$wgVisualEditorEnableWikitext = true;
$wgDefaultUserOptions['visualeditor-newwikitext'] = 1;

Namespace selection

VisualEditor is available in the main namespace by default, plus User, File and Category. Extend or restrict this list per namespace:

$wgVisualEditorAvailableNamespaces = [
    'Project' => true,   // add Project pages
    'File'    => false,  // disable in File namespace
    'Extra'   => true,   // custom namespace (by name or numeric id)
];

Mobile and section editing

VisualEditor works with the mobile skin (Minerva) out of the box. Section editing from the mobile interface is controlled separately:

// 'never', 'desktop', 'mobile', 'always' — default restricts to mobile
$wgVisualEditorEnableVisualSectionEditing = 'mobile';

Additional settings worth knowing

• Change tagging — $wgVisualEditorUseChangeTagging (default true) tags edits with visualeditor, which is what lets you filter VE edits in recent changes and statistics
• Edit check — $wgVisualEditorEditCheck enables the experimental "edit check" feature that flags common problems (like missing citations) before save
• Beta integration — the BetaFeatures integration was removed; $wgVisualEditorEnableBetaFeature exists only as a legacy option
• Content models — $wgVisualEditorAvailableContentModels maps additional content models to editors

Troubleshooting checklist

• Not listed in Special:Version — syntax error or missing wfLoadExtension; check the PHP error log and clear the opcode cache if you use opcache
• "Error contacting the Parsoid/RESTBase server" — on 1.42+, test curl https://your.wiki/rest.php/v1/page/Main_Page; a 404 means the rest.php rewrite rule is wrong, a 403 points at server permissions. On 1.35–1.41, check the $wgVirtualRestConfig URL and that the Parsoid service is reachable from the web server
• Templates show as puzzle icons — TemplateData is not enabled; load it with wfLoadExtension( 'TemplateData' ); (it is bundled)
• Editor loads forever — open the browser console: 404s on rest.php requests, missing mediawiki.page.ready-era modules or a blocking CSP are the usual culprits; for private wikis on 1.35–1.41, verify cookie forwarding
• Subpage titles fail — with Apache, ensure AllowEncodedSlashes NoDecode on the virtual host so titles with slashes reach rest.php intact
• Anonymous users see only wikitext — check $wgVisualEditorDisableForAnons and the visualeditor-editor default preference

Further reading

The Extension:VisualEditor page documents every configuration variable, and Parsoid covers the parser integration. For wikis still on 1.41 or older, the legacy installation guide remains the reference. On current releases, the short version is: load the extension, check Special:Version, and use the defaults — the era of fiddly Parsoid service setup is over.