Wikipedia:VisualEditor/User guide

From Wikipedia, the free encyclopedia
Jump to: navigation, search
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, if you are using one of the supported browsers, 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, the only way they can use VisualEditor is by specifying the URL parameter.) 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[edit]

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.

VisualEditor - Edit tab - 2.png

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.

Section editing VE Sep2013.png

Getting started: the VisualEditor toolbar[edit]

The VisualEditor toolbar
The VisualEditor toolbar appears at the top of the screen when you begin editing through VisualEditor. It includes some familiar icons:

VisualEditor - Toolbar - Undo-redo.png
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.)

VisualEditor - Toolbar - Headers.png
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").

VisualEditor - Toolbar - Formatting.png
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 ("Clear styling") removes whatever formatting is currently applied to selected text.

VisualEditor - Toolbar - Linking.png
Linking tool: The chain is the linking tool.

VisualEditor - Toolbar - Lists and indentation.png
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.

VisualEditor insert menu 01 January 2014.png
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.)

VisualEditor - Toolbar - SpecialCharacters.png
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.

VisualEditor - More Settings.png
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[edit]

When you're done editing click the green "Save page" button in the toolbar.
VisualEditor - More Settings.png

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.)

New VE save dialog.jpg

Editing links[edit]

VisualEditor - Toolbar - Linking.png
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.

VisualEditor - Link editing inline 2.png
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.

VisualEditor - Link editing inline.png
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[edit]

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.
VisualEditor insert menu 01 January 2014.png

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.

VE insert media 7.13.png

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.
VisualEditor - Media editing 3.png

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.

VisualEditor - Media editing 6.png

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[edit]

Adding a new reference[edit]

VisualEditor references more.png
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.

VisualEditor reference tool.png
When you click on the "Reference" icon, it will open a submenu with many options similar to those in the toolbar.

VisualEditor reference toolbar transclusion.png
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.

VisualEditor - Editing references 9.png
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.

VisualEditor - Editing references 20.png
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.

VisualEditor - Editing references 10.png
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).

VisualEditor - Editing references 11.png
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[edit]

VisualEditor - Editing references 1.png
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.

VisualEditor - Editing references 6.png
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.

VisualEditor - Editing references 3.png
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.

VisualEditor - Editing references 5.png
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.

VisualEditor - Apply changes.png
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[edit]

VisualEditor references more.png
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.

VisualEditor - Editing references 18.png
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[edit]

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.
VisualEditor reference toolbar transclusion.png

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.
VisualEditor - Template editing 4.png

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.
VisualEditor - Template editing 1.png

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.
VisualEditor - Template editing 3.png

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.

VisualEditor - Template editing 2b.png

When you're done, click "Apply changes" to close the dialog and return to the main editing page.
VisualEditor - Apply changes.png


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.

VisualEditor - Template editing 5.png

Substituting templates[edit]

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.

VisualEditor - Template editing 7.png

Add any parameters as usual and "Apply changes".
VisualEditor - Template editing 6.png

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.
VisualEditor - Template editing 8.png

Editing categories[edit]

VE toolbar more settings.png
To edit a page's categories, click to open the "more settings" pulldown menu in the toolbar.

VisualEditor - More Settings.png
The "more settings" pulldown menu opens access to the "Categories" button.

VisualEditor - Category editing 1.png
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 "à".

VisualEditor - Category editing 3.png
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.

VisualEditor - Category editing 2.png
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.

VisualEditor - Apply changes.png
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[edit]

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[edit]

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 VisualEditor - Icon - Bold-b.svg Cmd+B Ctrl+K Insert link VisualEditor - Icon - Link.svg Cmd+K

Ctrl+I Italics VisualEditor - Icon - Italic-i.svg Cmd+I Ctrl+X Cut Cmd+X

Ctrl+Z Undo VisualEditor - Icon - Arched-arrow-rtl.svg Cmd+Z Ctrl+C Copy Cmd+C

Shift+Ctrl+Z Redo VisualEditor - Icon - Arched-arrow-ltr.svg Shift+ Cmd+Z Ctrl+V Paste Cmd+V