MediaWiki VisualEditor & WYSIWYG — Parsoid, VE Configuration, and Editor Integration

In this tutorial, you will learn about MediaWiki VisualEditor & WYSIWYG. We cover key concepts, practical examples, and best practices to help you master this topic.

VisualEditor brings WYSIWYG editing to MediaWiki, allowing users to edit pages without learning wikitext — powered by Parsoid for wikitext-to-HTML conversion, with customizable toolbars and deep integration that makes Wikipedia more accessible to newcomers.

What You'll Learn

• Installing VisualEditor and Parsoid
• Configuring the VisualEditor toolbar
• Customizing editor settings
• Understanding Parsoid architecture
• Integrating with other extensions
• Troubleshooting common VE issues

Why It Matters

Wikitext is a barrier to entry. Many potential contributors are intimidated by the markup syntax. VisualEditor removes that barrier by providing a familiar word-processor interface. Users can bold text, add links, insert tables, and upload images without writing a single wiki character. For organizations adopting MediaWiki as a documentation platform, VisualEditor is often the difference between a wiki that gets used and a wiki that gets ignored.

Real-World Use

A DodaTech wiki opens documentation contributions to all employees, not just developers. Non-technical team members from marketing, support, and product teams contribute using VisualEditor. They edit pages, format text, add screenshots, and create links — all without learning wikitext. The developer team still uses source editing for complex templates. Both groups coexist on the same pages.

Learning Path

flowchart LR
  A["25: Extension Installation"] --> B["26: Semantic MediaWiki"]
  B --> C["27: VisualEditor"]
  C:::current
  D["28: Scribunto & Lua"]
  E["29: Cite & References"]
  F["30: Interwiki Links"]

  C --> D --> E --> F

  classDef current fill#38bdf8,color#0f172a,stroke-width:2px

What Is VisualEditor?

VisualEditor is a rich-text editor that works like Google Docs or Microsoft Word. It renders wiki pages as formatted text during editing. Users select text and click toolbar buttons for formatting, rather than typing '''bold''' or [[link]].

Key Features

• WYSIWYG editing: What you see is what you get
• Toolbar: Buttons for formatting, links, headings, lists, tables, media
• Drag and drop: Rearrange images, sections, and content blocks
• Citation tool: Insert references and footnotes
• Special character insertion: Accents, symbols, and non-Latin scripts
• Visual diff: See changes as formatted text, not wikitext diffs

Step 1: Install VisualEditor

Download VisualEditor

cd /opt/lampp/htdocs/mediawiki/extensions
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/VisualEditor.git
cd VisualEditor
git checkout REL1_42

Install Parsoid (Modern Method)

MediaWiki 1.42+ bundles Parsoid as a Composer dependency:

cd /opt/lampp/htdocs/mediawiki
composer install

If composer is not available:

apt install composer
composer install

Enable VisualEditor

In LocalSettings.php:

wfLoadExtension( 'VisualEditor' );

// Enable by default for all users
$wgDefaultUserOptions['visualeditor-enable'] = 1;

// Enable VisualEditor for namespace 0 (main)
$wgVisualEditorAvailableNamespaces = [
    NS_MAIN => true,
    NS_TALK => true,
    NS_USER => true,
    NS_HELP => true,
    NS_PROJECT => true,
];

Step 2: Verify Installation

After enabling, edit any page. You should see two edit tabs:

• Edit: Opens the wikitext source editor
• Edit visual: Opens VisualEditor

If only the source editor appears, check that Parsoid is running properly. Go to Special:Version and confirm "VisualEditor" appears in the installed extensions list.

Testing Parsoid

Verify Parsoid is running:

curl http://localhost:8080/rest.php/localhost/v1/page/Main_Page

If Parsoid responds with JSON data, it is working. If not, check your web server configuration and Parsoid setup.

Step 3: Configure the Toolbar

The VisualEditor toolbar is configurable. You can enable, disable, or reorder buttons.

Toolbar Groups

// Customize the toolbar
$wgVisualEditorToolbarConfig = [
    'toolbarGroups' => [
        [
            'name' => 'formatting',
            'groups' => [ 'basic', 'textStyle', 'alignment' ]
        ],
        [
            'name' => 'insert',
            'groups' => [ 'media', 'reference', 'table', 'template' ]
        ],
        [
            'name' => 'tools',
            'groups' => [ 'specialCharacter', 'code' ]
        ],
    ],
];

Removing Buttons

Hide specific buttons you do not want users to access:

// Remove specific toolbar items
$wgVisualEditorPluginModules = [];
$wgVisualEditorHideSimpleToolbar = false;

// Disable the citation tool
$wgVisualEditorCiteTool = false;

Adding Custom Buttons

Extensions can add custom toolbar buttons. For example, the "Cite" extension adds citation buttons:

wfLoadExtension( 'Cite' );

This automatically adds "Cite" and "Insert reference" buttons to VisualEditor's toolbar.

Step 4: Namespace Configuration

Control which namespaces use VisualEditor:

// Enable VE on specific namespaces
$wgVisualEditorAvailableNamespaces = [
    NS_MAIN => true,
    NS_USER => true,
    NS_PROJECT => false,   // Disable on project pages
    NS_TEMPLATE => false,  // Disable on templates
];

// Enable VE for all namespaces
$wgVisualEditorAvailableNamespaces = [
    '_merge' => true,  // Enable globally
];

Per-User Defaults

Users can set their default editor in preferences:

Editing mode:
  ☐ Always use VisualEditor
  ☐ Always use source editor
  ☐ Remember my last editor

Set the wiki-wide default:

$wgDefaultUserOptions['visualeditor-enable'] = 1;

Step 5: VisualEditor and Templates

VisualEditor supports template editing through a dialog interface.

Template Dialog

When a user clicks a template in VisualEditor, a dialog shows:

• Template name
• Parameter fields with descriptions
• Preview of rendered output
• "Apply" and "Cancel" buttons

Template Data

For the dialog to show useful parameter fields, templates should have <templatedata> annotations:

{
    "description": "A notice box for important information",
    "params": {
        "1": {
            "label": "Message",
            "description": "The notice content",
            "type": "string",
            "required": true
        },
        "type": {
            "label": "Type",
            "description": "info, warning, or error",
            "type": "string",
            "default": "info"
        }
    }
}

Add this JSON inside <templatedata> tags on the template page. VisualEditor reads it and displays the parameter fields in the dialog.

Step 6: Integration with Other Extensions

Cite Extension

The Cite extension adds citation insertion to VisualEditor:

wfLoadExtension( 'Cite' );

Users can insert footnotes using the "Cite" button in the VE toolbar.

ConfirmEdit

The ConfirmEdit CAPTCHA extension triggers when saving in VisualEditor. Users may need to solve a CAPTCHA before saving.

PageForms

PageForms integrates with VisualEditor to provide form-based page creation.

Semantic MediaWiki

SMW annotations can be edited in VisualEditor through the "Properties" dialog, though full SMW query editing still requires source mode.

Step 7: VisualEditor for Mobile

VisualEditor works on mobile devices with Responsive Design:

• Toolbar collapses: Buttons are grouped under expandable menus
• Larger touch targets: Buttons are sized for finger tapping
• Simplified interface: Fewer toolbar items to reduce clutter

Enable mobile support:

// Enable VE on mobile
$wgVisualEditorEnableMobile = true;

Mobile vs Desktop Differences

• No drag-and-drop on mobile
• Limited keyboard shortcuts
• Smaller editing area

Step 8: Troubleshooting VisualEditor

Common Issues

What You Learned

• VisualEditor provides WYSIWYG editing powered by Parsoid
• Parsoid converts wikitext to HTML and back
• The toolbar is configurable with groups and individual buttons
• Templatedata adds parameter descriptions to the template dialog
• VE integrates with Cite, PageForms, ConfirmEdit, and SMW
• Mobile support provides responsive editing
• Common issues include Parsoid connection problems and missing templatedata

In the next lesson, you'll learn about Scribunto and Lua scripting.

Common Mistakes

Practice Questions

1. What is the role of Parsoid in the VisualEditor architecture?
2. How would you disable VisualEditor for the Template namespace while keeping it enabled for articles?
3. What is templatedata and why is it important for template editing in VisualEditor?
4. Challenge: Set up VisualEditor for a production wiki. Install VE and Parsoid. Configure the toolbar to remove the "Special character" button and add a custom "Cite" button. Enable VE for main, user, and help namespaces but disable it for template and category namespaces. Create a template with templatedata and verify the dialog shows parameter fields. Test editing a page with both VE and source editor, switching between them. Document the VE configuration for future administrators.

FAQ

Mini Project

Goal: Deploy and customize VisualEditor for a team wiki.

1. Install VisualEditor and configure Parsoid
2. Verify VE is working by editing a test page
3. Customize the toolbar:
   • Keep: Bold, Italic, Link, Heading, List, Media, Table
   • Remove: Special character, Code block, subscript/superscript
4. Add templatedata to 3 existing templates on your wiki
5. Configure VE to be enabled on main namespace but disabled on template namespace
6. Set the default editor preference to VisualEditor for new users
7. Test the complete workflow: create a new page in VE, add formatting, insert an image, add a template with the dialog, add a citation, and save
8. Switch to source mode and back to verify round-trip editing works
9. Create a "VisualEditor Guide" help page for your wiki users

What's Next

VisualEditor makes editing accessible. Now let's unlock the full power of programmable templates with Lua.

Continue to Lesson 28: Scribunto & Lua — learn how to write Lua modules for advanced template logic and dynamic content generation.