How to Enable and Configure VisualEditor for Collaborative Editing in MediaWiki

VisualEditor gives MediaWiki users a true WYSIWYG experience, letting them edit pages without learning wikitext syntax. The extension is bundled with MediaWiki 1.35+ and can be enabled with a few lines in LocalSettings.php. This guide walks through the whole process – from compatibility checks to advanced configuration – and provides a concise troubleshooting checklist.

1. Prerequisites

• MediaWiki version: 1.35 or newer. Versions 1.35 & later ship VisualEditor in the extensions/ directory. Older wikis must upgrade first.
• PHP extensions: curl (or php‑curl) and zlib. Both are required for the bundled Parsoid REST service.
• Web server: Apache or Nginx with short‑URL support is recommended, but not mandatory.
• Write permissions on the MediaWiki directory so you can edit LocalSettings.php and clear the cache.

2. Installing the extension

Because VisualEditor is already present in the source tree, the installation step is simply loading the extension.

# At the bottom of LocalSettings.php
wfLoadExtension( 'VisualEditor' );

After saving the file, run the schema updater (or visit Special:Version to confirm that VisualEditor appears in the list).

3. Basic activation for all users

The following optional settings make VisualEditor the default editor and prevent users from disabling it.

// Enable VisualEditor for every logged‑in user by default
$wgDefaultUserOptions['visualeditor-enable'] = 1;

// Hide the opt‑out checkbox in user preferences
$wgHiddenPrefs[] = 'visualeditor-enable';

// Make VisualEditor the default editor for anonymous users (optional)
$wgDefaultUserOptions['visualeditor-editor'] = 'visualeditor';

If you prefer a beta‑opt‑in model, omit the hidden preference and let users enable VisualEditor themselves.

4. Enabling the integrated wikitext mode (the 2017 editor)

VisualEditor can also expose a lightweight wikitext editor inside the same interface.

$wgVisualEditorEnableWikitext = true;          // turn on the feature
$wgDefaultUserOptions['visualeditor-newwikitext'] = 1; // enable by default
$wgHiddenPrefs[] = 'visualeditor-newwikitext'; // prevent opt‑out

5. Controlling the edit‑tab layout

MediaWiki traditionally shows two edit tabs: "Edit" (VisualEditor) and "Edit source" (wikitext). You can collapse them into a single tab that remembers the last editor used.

$wgVisualEditorUseSingleEditTab = true;                     // one tab only
$wgDefaultUserOptions['visualeditor-tabs'] = 'prefer-ve'; // default to VE
$wgDefaultUserOptions['visualeditor-editor'] = 'visualeditor'; // ensure VE is used first

To hide the tab completely (e.g. for a read‑only wiki), set $wgVisualEditorUseSingleEditTab = false and remove the VisualEditor entries from the skin’s tab list.

6. Namespace selection

By default VisualEditor works in the main content, user, file and category namespaces. You can add or remove namespaces with the associative array $wgVisualEditorAvailableNamespaces.

$wgVisualEditorAvailableNamespaces = [
    // Enable for Project pages, disable for File pages, add a custom namespace "Extra"
    'Project' => true,
    'File'    => false,
    'Extra'   => true,
];

Use the canonical namespace names (e.g. Project, Talk) or numeric IDs for custom namespaces.

7. Apache‑specific tweaks

VisualEditor needs the server to accept URLs that contain slashes (subpages) and, when short URLs are used, proper rewrite rules.

• Allow slashes in page titles – add the following directive to the <VirtualHost> section:

AllowEncodedSlashes NoDecode

• Short‑URL rewrite – ensure that the rest.php request is not intercepted by the short‑URL rule. A common pattern is:

RewriteCond %{REQUEST_URI} !^/rest.php
RewriteRule ^(.*)$ index.php?title=$1 [L,QSA]

If you use Nginx, the equivalent location /rest.php block must be placed before the generic rewrite.

8. Parsoid – the backend parser

VisualEditor talks to Parsoid via MediaWiki’s built‑in REST API. For most installations the default configuration works out of the box:

$wgVirtualRestConfig['modules']['parsoid'] = [
    // The URL is built from $wgServer and $wgScriptPath, e.g. http://example.org/rest.php
    'url' => $wgServer . $wgScriptPath . '/rest.php',
];

If your wiki runs behind a proxy, inside Docker, or on a separate host, replace the URL with the reachable address, e.g. http://parsoid.internal:8000/rest.php. When you change this value, make sure the domain entry matches the $wgServer hostname of the Parsoid instance.

When the wiki is private (read‑access restricted), forward the user’s cookies so Parsoid can authenticate the request:

$wgVirtualRestConfig['modules']['parsoid']['forwardCookies'] = true;

Security note: forwarding cookies over HTTP exposes authentication data. Use HTTPS or restrict this option to private wikis only.

9. Optional advanced features

• Beta‑feature flag: $wgVisualEditorEnableBetaFeature = true; – shows a banner that lets users opt‑in.
• Visual diffs on history pages: $wgVisualEditorEnableDiffPage = true;
• Section editing on mobile: $wgVisualEditorEnableVisualSectionEditing = 'mobile';
• Change‑tagging (useful for analytics): $wgVisualEditorUseChangeTagging = true;

10. Troubleshooting checklist

1. Extension not listed in Special:Version – Verify that the line wfLoadExtension('VisualEditor'); is present and that there are no syntax errors in LocalSettings.php. Clear the PHP opcode cache if you use opcache.
2. "Error contacting the Parsoid/RESTBase server" – Check the URL in $wgVirtualRestConfig. Test it directly: curl $wgServer/rest.php/v1/page/Main_Page. A 404/403/500 response indicates a mis‑configured url or missing permissions.
3. Subpage editing fails – Ensure AllowEncodedSlashes NoDecode is set in Apache and that the virtual host is reloaded.
4. VisualEditor loads forever – Look at the Parsoid log (usually /var/log/parsoid.log or the Docker container’s stdout). Common causes: missing php‑curl, expired SSL certificates, or SELinux blocking the port.
5. Templates appear as puzzle icons – Verify that the TemplateData extension is installed and that the mw:Transclusion JSON is generated. See the MediaWiki talk page VisualEditor/2019 for details.
6. Anonymous users cannot edit – Set $wgDefaultUserOptions['visualeditor-editor'] = 'visualeditor'; and ensure $wgGroupPermissions['*']['edit'] is true, or explicitly enable it for anons with $wgVisualEditorDisableForAnons = false;.

11. Final verification

After all changes, clear the MediaWiki cache (php maintenance/eval.php "clearCache();" or use the purge button on Special:Version) and reload a wiki page. You should see the VisualEditor edit tab (or a single combined tab) and be able to edit the page without seeing raw wikitext markup.

12. Further reading

The official extension page contains the exhaustive list of configuration variables and the latest development notes: Extension:VisualEditor.