Help:VisualEditor

---

• Main page
• Feedback at MediaWiki
• Sandbox (no account required)

---

About

---

• Why are the developers building this? (2013)
  • User Test Data (2013)
• Documentation:
  • Introductory tutorial
  • User guide
  • Keyboard shortcuts
  • Frequently Asked Questions (or at MediaWiki)
• Development:
  • Roadmap up to 2017
  • Updates (2013-2023)
  • Weekly status reports (2015-2016)

---

Help out

---

• Update the help pages
• Add template data (Tutorial)
• Translate and localize documentation

---

Research

---

• Main research page

---

Other

---

• Customization
• Known problems
• Requests for Comments (RfCs): Jul 2013 a, Jul 2013 b, Jul 2015, Sep 2015

If you would like to try VisualEditor without editing an article, here is a page where you can freely do so. You don't need an account to use it.

In Wikipedia, you can edit pages using the new VisualEditor (VE) interface, or using the classic wiki markup (wikitext) interface. VisualEditor is available alongside the original wikitext editor if you opt-in, by changing your preferences. (Because unregistered editors cannot specify preferences, they cannot currently use VisualEditor.) After you opt-in, you can use VisualEditor by clicking Edit beta, which you'll see at the top of pages, and next to section headings. Similarly, you can instead use the wikitext editing interface by clicking Edit source.

VisualEditor is available on the following types of pages (namespaces):

• Article ("mainspace")
• User
• Category
• Help
• File (but not with files, or other pages, at Wikimedia Commons)

This guide contains step-by-step descriptions, with screenshots, for editing that can be done with VisualEditor. Be aware that VisualEditor is still in development (thus "Beta"), so there are known limitations and bugs. For example, in many cases, particularly for large pages, you'll find that VisualEditor is slower than wikitext editing. While VisualEditor is still in development, you should review your changes to ensure that no unwanted modifications are done to the article.

Please note that this guide may temporarily be outdated when new features are released. Also, please feel free to report problems you encounter, and to offer comments or suggestions about VisualEditor, at the Feedback page.

Opening VisualEditor

To edit a page using VisualEditor, click on the "Editbeta " tab at the top of the page. It can take a few seconds for the page to open for editing, and longer if the page is very long. If instead you click on the "Edit source" tab, the page will open for editing using the classic wikitext source editor, not VisualEditor.
You can also open VisualEditor by clicking on the"Editbeta " link to the right of each section heading. When the page opens for editing, you'll be at that section; however, the whole page is still available for editing. It's better to use a section link, rather than the tab at the top, if you plan to edit only a single section. That's because clicking on a section link automatically puts the title of the section into the edit summary (as described in the Saving changes section, below). If the section title is in the edit summary, it indicates to other editors where in the article (page) you made changes.

Getting started: the VisualEditor toolbar

The VisualEditor toolbar

The VisualEditor toolbar appears at the top of the screen when you begin editing through VisualEditor. It includes some familiar icons:
	Undo and Redo the changes you've made. (One or both arrows are greyed out if you have nothing you can yet undo or redo.)
	The Change format pull-down menu allows you to change the header level of text. Standard section headings are at the "Heading" level, as shown in the illustration. (In wikispeak, this is "level 2".) In addition to changing the level of existing headers, you use this menu to create a header (select/highlight some text, then pick a level) and to convert an existing header to regular text (click anywhere within a header, then pick "Paragraph").
	Formatting: Clicking the "A" opens a submenu. The "bold" icon (B) bolds the selected text. The "italics" icon (I) italicizes the selected text. The "Subscript" icon (S2) causes the selected text to appear smaller than surrounding text and slightly below the line. The "Superscript" icon (S2) causes the selected text to appear smaller than surrounding text and slightly above the line. The "Strikethrough" icon (S) adds a solid bar through the selected text. The "Computer code" icon (a set of curly brackets: {}) changes the font display in the selected text to a monospaced font, to set it apart from surrounding text. The "Underline" icon (U) adds a solid line beneath the selected text. The last icon ("Remove") removes whatever formatting is currently applied to selected text.
	Linking tool: The chain is the linking tool.
	Lists & indentation: The first two icons allow you to make numbered or bullet lists, respectively. The last two allow you to increase or decrease the indentation level of content that you have selected.
	Insert: The "insert" pulldown on the VisualEditor toolbar leads to several additional actions, including adding references and transcluding templates. The "Media" icon (a picture of mountains) opens the media dialog. The "Reference" icon (a bookmark) opens a dialog to edit references. The "References list" icon (three books) opens a dialog to display references. The "Transclusion" icon (a puzzle piece) allows you to edit templates. The "special character" icon (Ω) allows you to insert some special characters. (See below.)
	Special character insertion: The "special character" icon allows you to pull up a subwindow with a number of special characters that you can place into the text. These include some standard symbols, accents and mathematical symbols.
	The More settings pulldown is next to the buttons that allow you to Cancel or save your changes. Under More settings are currently options to adjust page settings by edit categories and listing language links using the "Languages" icon (The letter A in the Latin alphabet and Japanese kana (あ)). In some browsers, you can also switch one-way from VisualEditor to the classic wikitext source editor. Cancel or save your changes. If you click "Cancel", you'll be asked to confirm that's what you want to do. If you click "Save page", you'll see a dialog box with final steps to do to complete your edit. "Save page" cannot be selected if you haven't changed the page.

Saving changes

When you're done editing click the green "Save page" button in the toolbar.
Now you'll see a small dialog box. Here you should enter a brief summary of your actions (in the box that says "Briefly describe the changes you have made"); this is the edit summary. The number at the bottom right of the box, which initially is 255, shows how much more text you still can enter into that box. You can click on the common edit summaries options, to select and paste a standard phrase to the dialog box. You can also mark your edit as minor, and you can add (or not add) the page you're editing to your Watchlist. If you click the "Review your changes" button (recommended), you will see a page that Wikipedia calls a diff. This shows, in wikitext format, the differences between the previous version of the page and what the page will be after you save it (if you don't change anything more). When you're on the "diff" page, if the differences (changes) look good, you should click "Return to save form" to continue the page save process. If, instead, you want to make further edits to the page, you should click the "^" in the upper right corner. Finally, after you've entered the edit summary, checked (or not) the minor page edit and page watch checkboxes, and reviewed (or not) your changes, you should click the "Save page" button to complete your edit. (If for some reason, at any point, you decide you want to return to editing, click the "^" in the upper right corner of the dialog box.)

Editing links

	Links can be added through the "Link" icon in the toolbar (the icon has two links, in a chain), or by using the shortcut Ctrl+K (or ⌘ Command+K on a Mac). You should first select (highlight) text, or place your cursor on a word, then click the "Link" icon, to insert a link for that text or word. [The text that was highlighted - what is visible to the reader - is known as the link label.] If you need to apply formatting to the word, make sure you do that before and apply a link only after that.
	Whether you use the icon or the shortcut, a dialog will open in which you specify the link - where the reader will go when he/she clicks on the text you've selected. (This is called the link target.) For an internal link (what Wikipedia calls a wikilink), just start typing the name of the page you want to link to. As you type, VisualEditor will try to assist by looking for likely matches. Actually selecting the internal link is a two-step process: Confirm: Make sure the VE checkmark is to the left of the internal link you want. If it's not, you can keep typing until it is, or - if you've finished typing, or don't want to type any more - you can click on the link you want, to move the checkmark. If you want to link to a page that doesn't (yet) exist (what Wikipedia calls a "red link"), the checkmark will be in place once the search can't find any possible match to what you've typed. Press ↵ Enter to confirm; at that point, the dialog box will not show any search options, just your choice. Finish: To close the dialog box, you can press ↵ Enter, click outside of the box, or click the close icon (<). Note 1: If you are creating an internal link to a specific section of a page, using the standard wikitext approach ("#Some section name"), VE will show the target page in red. You should ignore this. When you're finished typing the section name, do the two-step process as described above: ↵ Enter to confirm, and then close the dialog box. Note 2: If the link label and the link target are not the same, you're creating what is known in Wikipedia as a piped link. If you want an external link, type (or paste) the full url (http:// ..... ), then press ↵ Enter to confirm, and then close the dialog box. Once the dialog box has been closed, the link on the main editing page will show in blue. Like other changes you do in VisualEditor, it will not take effect (be visible to readers) until you save the entire page.
	To change or remove an existing link, click anywhere within the linked text, then click either the "Link" icon that appears near that text, or the same icon in the toolbar, or use the Ctrl+K keyboard shortcut while on the linked text. Any of these three actions will open the link dialog box. You can then edit (change) the link's target (see above). If you want to remove the target (and thus the link) altogether, click the "Remove" icon (trash can) in the top-right corner of the dialog box.

Editing images and other media files

To add a new image (or another type of media file) to the page, click the "Media" icon (a picture of mountains) in the Insert pulldown menu. The image will be added wherever your cursor is, so make sure that your cursor is not in the middle of a sentence or list.
Clicking the "Media" icon opens a dialog that automatically searches this Wikipedia and Wikimedia Commons for media files, using the name of the page you are editing. If you want to search on text other than the name of the page you are editing, just change the text in the search box. To select a specific file to insert, from the choices that the search shows, click once on the thumbnail picture of the file you want.
Once inserted, the image can be modified. First, select it by clicking on it (it will then appear with a blue background). You can resize it using the handles at its corners. You can also drag and drop it to a different location.
To add a caption, or edit an existing one, select the image, then click on the "Media" icon that appears in the upper right of the image. The dialog then allows you to add (or edit) the caption. You are not limited to plain text - the caption can contain formatting and/or links. When you're done, click "Apply changes" to close the dialog and return to editing the page.
To replace an image or media file, click on it to select it (as mentioned, it will then have a blue background), and then click on the media icon in the Insert pulldown menu. You'll then be able to select the replacement image or file. (Note: If you want to retain/reuse the caption, you should copy the caption to the clipboard before starting the replacement sequence; it's then available to paste once the new image is in place and you want to add a caption for that.)
To delete an image or media file, select it, and then press delete or ← Backspace.

Editing references

Adding a new reference
	To add a new reference, put the insertion marker at the place in the text where you want to add that new reference. Then click on the "Reference" icon (bookmark) in the "Insert" pulldown toolbar.
	When you click on the "Reference" icon, it will open a submenu with many options similar to those in the toolbar.
	When adding a new reference, many editors create the content using a template, such as "Cite web" or "Cite journal", rather than typing text directly. If you want to use a template, click the Transclusion icon (puzzle piece) in the "more" pulldown of the toolbar of the reference dialog box.
	Then, look for the template you want to use, add it, and edit it as you would an existing template. (For more details on doing this, see the Editing templates section, below.) Click on "Apply changes" to return to the main reference dialog, and then "Apply changes" again to return to the main editing page.
	In the reference dialog box, you can add, edit, and format your citation directly. You can include a web address (URL). In the "Options" section, you can make the reference belong to a specific group. This is done, for example, when an article has separate sections for notes and for citations. Most articles only have one group of footnotes, which appear in a section called "References". If you are editing that kind of article, the "Use this group" field should be left blank. After you've finished creating a reference, click "Apply changes" (bottom right corner of the dialog box) to return to the main editing page.
	If you have just added the first reference(s) to a page, you need to do three things in order for the text of your reference(s) to be properly displayed. First, at the bottom of the page (if it is an article), just above the "Further reading" section, if there is one, or, if not, just above the "External links" section, you need to create a new section, called "References". Type that word (without quotation marks), select (highlight) it, then use the "Change format" pulldown menu (see above) to make that word into a heading. Second, place the cursor below this new section heading. Then, in the "Insert" pulldown menu, click the "References list" icon (three books).
	Third, in the references list dialog box, click "Apply changes" to specify that this is where you want the list (text) of references to appear. As mentioned above, the "Options" section (and, specifically, the "Use this group" box) is used only if there are two or more types of footnotes. If there are, and you're creating a new section for something other than basic footnotes/references, you'll use this box. (For example, you might type "Notes" into the box.) But normally there is only one group of footnotes, and this box should be left blank.
Editing an existing reference
	To edit an existing reference (citation), click on its number, in the text, and then click the "Reference" icon (bookmark) that appears near it, or the one in the "Insert" pulldown toolbar.
	A dialog will open that includes a box where you can edit the text for that reference. You can format that text in the same way you can on the main editing page. For example, you can add italics or links.
	If the reference was created using a template, two things will happen when you click on the text of the reference: the text will be boxed, with a blue background, and a Transclusion/Template icon (puzzle piece) will appear. To edit the template parameters that make up the reference, you must click on the puzzle piece icon.
	After you click the Transclusion icon, you can edit each of the template's individual parameters. (For more details on doing this, see the Editing templates section, below.) When you're done editing the template, click "Apply changes", and you'll go back to the main reference dialog box.
	If there is nothing more to edit, in the main reference dialog box, click again on "Apply changes" to return to the main editing page.
Adding an existing reference to a new place
	A reference can be used in multiple places on a page, if it supports the text at each of those places. To use (or reuse) an existing reference, place your cursor in the text where you want to add that reference. Then enter the "Insert" pulldown on the toolbar and click on the "Reference" icon (bookmark). You'll now see the Reference dialog box. At the bottom left, click "Use an existing reference", which will get you to a list of all the existing references.
	If there are many references, you can scroll through them to find the one you want. Or you can use the search bar to look for specific text (one or more words next to each other). When you find, in the list, the reference you want to reuse, select it (click on it). Then click the "Insert reference" button (bottom right) to insert that reference into the text of the page you are editing, at the place you placed your cursor.

Editing templates

To add a new template to the page, place your cursor where you want the template to be inserted, and click on the "Transclusion" icon (puzzle piece) in the "Insert" pulldown toolbar.
In the dialog box, start typing the name of the template you want to insert. When you see the template name appear in the list, you can click "Add template" if the checkmark is next to the template you want. Or, at any point, you can just click on the template you want, once its name is visible, then click "Add template". If you are using the Monobook skin, this list may not appear. Try using the default, Vector skin instead.
You can also edit a template that is already on the page by selecting it (clicking on it); it will turn blue to show it has been selected. Then click the "Transclusion" icon (puzzle piece) that appears on or near the template, or click that same icon in the "Insert" pulldown toolbar.
If you are adding a new template, any parameters that have been defined in TemplateData as being required will be automatically added. If TemplateData has not been defined, then a link to the documentation will be available in the dialog. Add other parameters by clicking on the "Add parameters" button. You can edit the value of parameters that are listed on the left, or even delete them – just click in the box to change the value.
For complex, multi-part transclusions, click on "Show options". Templates, content blocks, and parameters for the transclusion you selected will be listed on the left. To see the parameters you can add, clicking on the template name, on the left side of the dialog box, if you don't already see a list of possible parameters on the right side. To add a specific parameter, from the list, click on its name (don't double-click). If you don't see the parameter you want to select (click), you can use the search box to see if you can find it, then click on its name.
When you're done, click "Apply changes" to close the dialog and return to the main editing page.
Sub-templates
When a template embeds other templates, these sub-templates will appear inside the parameters that display them. They can be edited or removed inside the parameter field. New sub-templates are added by following the steps of adding a parameter. You may need to check the template documentation to make sure that the sub-template is supported.
Substituting templates
When a template must be substituted, you must type subst: (colon included) before the template's name. Autocompletion doesn't work with subst:; if you need the autocompletion, add subst: only after finding the template you're looking for. Then, click the green "Add template" button.
Add any parameters as usual and "Apply changes".
During this initial phase of implementing VisualEditor, a substituted template will not expand on the main page after your leave the dialog box. Only after you finish making changes and save the page will substitution go into effect; the results of the substitution will be visible the next time someone edits the page using VisualEditor.

Editing categories

	To edit a page's categories, click to open the "more settings" pulldown menu in the toolbar.
	The "more settings" pulldown menu opens access to the "Categories" button.
	A dialog opens that lists existing categories for the page, and allows you to add new ones. In the "Options" section, you can define how the page will be listed (sorted) on the category pages. For example, an article about "John Smith" probably is best if sorted by last name (Smith), then first name (John). In that case, the sort key would be (without quotation marks) "Smith, John". Accented characters will misfile, so replace them by plain characters: "a" rather than "à".
	To add a new category, enter its name in the field labeled "Add a category". You do have the option of adding a category that does not (yet) exist, but this is strongly recommended against.
	To remove an existing category, click on it and then, in the dialog that opens, click on the "Remove" icon (trash can). In that dialog, you can also specify the sorting key for a specific category. This overrides the general (default) sorting key, for just that specific category.
	Click "Apply changes" (in the bottom right corner of the dialog box) when you're done editing categories; you'll then be returned to the main editing page.

What VisualEditor can't be used for

Some items, including hidden text, image galleries, mathematical formulae, and music scores, are not yet supported by VisualEditor. Until they are supported, you will need to edit the source wikitext directly (using the "Edit source" tab) if you want to change or add these items.

VisualEditor cannot yet change the formatting of tables, including adding or deleting rows or columns. However, the contents of existing table cells can be edited.

You cannot copy-paste from one page to another without losing italics, bold, wikilinks, and other markup. In particular, footnotes and templates cannot be copy-pasted from one page to another while using VisualEditor.

You cannot post your signature (which is provided in Flow) or use any wiki code.

Keyboard shortcuts

Keyboard shortcuts allow editors to quickly do formatting without clicking toolbar icons. Common general shortcuts, and shortcuts used by other editing software, also work in VisualEditor. A complete list can be found here, plus a full list of mouse and keyboard interactions. The more common keyboard shortcuts are listed below:

PC shortcut	Action	Symbol	Mac shortcut			PC shortcut	Action	Symbol	Mac shortcut
Ctrl+B	Bold		⌘ Cmd+B			Ctrl+K	Insert link		⌘ Cmd+K
Ctrl+I	Italics		⌘ Cmd+I			Ctrl+X	Cut		⌘ Cmd+X
Ctrl+Z	Undo		⌘ Cmd+Z			Ctrl+C	Copy		⌘ Cmd+C
⇧ Shift+Ctrl+Z	Redo		⇧ Shift+⌘ Cmd+Z			Ctrl+V	Paste		⌘ Cmd+V