View source for Extension:VisualEditor

{{original|mw:{{PAGENAME}}}}
{{Bundled|1.35}}
{{MwNote|VisualEditor에 대한 설정 과정은 Parsoid가 코어 미디어위키에 통합된 미디어위키 1.35에서 크게 간소화되었습니다. 다음 지침은 MW 1.35 이상을 사용한다고 가정합니다; 만약 이전 버전을 사용하면, [[mw:Special:PermanentLink/4040509|이 페이지의 이전 버전]]을 참조하십시오.}}

'''VisualEditor''' 확장은 페이지를 풍부한 컨텐츠로 편집하도록 허용합니다. 그것은 "VisualEditor"라고도 하는 JavaScript 라이브러리를 기반으로 하며, 미디어위키 외부에서도 잠재적으로 사용될 수 있습니다. 이 페이지에서는 VisualEditor 확장을 설치하고 구성하는 방법에 대한 지침을 다룹니다. 사용에 대한 도움말에 대해, {{Mwll|Help:VisualEditor}}를 참조하십시오. 확장 기능과 라이브러리 개발에 대한 정보에 대해, {{Mwll|mw:VisualEditor|VisualEditor}}를 참조하십시오. 

__TOC__

== 얼마나 유용할까? ==
몇 년전에 시각 편집기를 사용해 보려고 시도할 때에는 미디어위키 자체의 이해가 부족했는지 위키텍스트 편집에 비해 효율이 떨어진다고 생각했습니다. 

이제, 2022년 중반에 시각 편집기는 초보자뿐만 아니라 숙련자에게도 상당한 도움이 됩니다. 그 이유는 적어도 강력한 자동 완성과 즉각적인 내용의 확인에 있습니다. {{red|철자 교정은 보통 브라우저의 사전으로 어느 정도 가능합니다. 단지, 사전의 능력이 그렇게 우수하지는 않은 것으로 판단됩니다.}}

사실, 템플릿을 만들어서 구성할 때에는 미디어위키 자체의 이해도가 상당히 높아야 하기 때문에, 대체로 다른 위키, 특히 위키피디아의 템플릿을 가져와서 적절히 수정해서 사용하는 것을 선호합니다. 

이런 측면에서 템플릿, 내부 링크 등의 자동 완성은 상당한 작업의 효율을 높여줍니다.

역시, 영문 위키피디아 번역에서도 원래의 링크를 복사해서 번역과 함께 링크를 만들어야 하는데, 이 작업과 관련해서 많은 시간이 소모되던 것도 역시 복사된 내용이 자동으로 완성되어서 오히려 시간이 단축됩니다. 

게다가, 위키텍스트는 미리보기를 해서 일일이 내용을 읽어서 수정할 곳을 찾아야 하지만, 시각 편집기는 지금 작성하고 있는 글 자체가 거의 완성된 글이기 때문에, 마지막 작업에 소요되는 상당한 시간을 줄여주는 것뿐만 아니라, 오타의 양을 대폭적으로 줄여줍니다. 

역시, 위키텍스트에서의 자주 사용하던 일부 명령은 키보드 단축키를 지정해 둠으로써 마우스의 이용을 줄여서 편집 시간을 단축시킬 수 있습니다. 예를 들어, {{Key press|[|[}}를 누르면, 자동으로 링크 창이 올라옵니다. 

전체적으로, 위키텍스트의 구문을 알던 모르던 시각 편집기는 이제 필수적인 도구임에 틀림없습니다. 

어쨌든, 먼서 설정을 해야 시각 편집기의 유용성을 확인할 수 있기 때문에, 이 문서 외에도, [[MediaWiki/Install 1.36.0 on Debian]]과 [[MediaWiki/Extensions]]를 참조하십시오. 

===advantages===

두 말할 필요 없이 시각 편집기는 사용할 수 있으면 사용하는 것을 추천합니다. 아래는 사용하면서 느낀 장점들입니다:

* 위키 키워드를 전혀 몰라도 위키 편집 가능
* 강력한 검색을 통한 자동 완성
* 번역기 확장에서 번역을 하거나, 기사에서 해당 문장 내의 수식은 수식 관련 키워드를 포함하지만, 시각 편집기 내에서 복사한 후에 붙여 넣기를 하면  수식 키워드를 포함하지 않습니다.

=== disadvantages ===
과연 모든 것이 좋을까? 그렇지는 않습니다. 

* 위키텍스트 편집기는 이미지 등의 미디어를 그것의 링크 정보로 지정하지만,  시각 편집기는 직접 화면에 그것을 보여야 하기 때문에, 처음 로딩에서 이미지가 많을수록 점점 더 시간 소모적이 됩니다.
* 블록 형태로 지정된 것을 편집할 때, 편집 창이 한 줄로 표시되기 때문에, 여러 줄에 걸쳐서 내용을 작성하거나 확인하기가 불편합니다.
* 시작 편집기에서 저장 후, 브라우저에서 캐싱이 남아서 브라우저 캐시를 비우는 과정이 필요할 수 있습니다.

{{Red|비록 일부 단점이 있다고 하더라도, 장점의 강력함을 생각하면 시각 편집기를 선택함에 전혀 장애가 되지 않습니다.}}

== Installation == 

[https://www.mediawiki.org/wiki/Special:ExtensionDistributor/VisualEditor 미디어위키 확장 내려받기 지면]에서 해당하는 버전을 다운로드하고 위키의 extensions 디렉토리에 VisualEditor에 푸십시오.

또는 개발자와 코드 기여자는 대신 다음을 사용하여 [[mw:Download from Git|Git에서]] 확장 프로그램을 설치해야 합니다.
<syntaxhighlight lang="bash">
cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/VisualEditor
</syntaxhighlight>

미디어위키 설정 [[Manual:LocalSettings.php|LocalSettings.php]]에 다음을 추가하십시오:
<syntaxhighlight lang="php">
wfLoadExtension( 'VisualEditor' );
</syntaxhighlight>

[[Special:Version]]에 접근해서 확장이 정상적으로 설치가 되었는지 확인하십시오.

== Download ==
=== For the General User ===
만약 미디어위키 타르볼을 다운로드했다면, 이 확장을 다운로드할 필요가 없습니다.

=== If you are using Git ===

{{MwNote}}'''Note:'''
* VisualEditor’s master branch contains the latest code, as used at Wikimedia. This code is potentially slightly buggy or unstable, but is likely to have fewer bugs and more features than old builds.
* '''The master branch requires alpha builds of MediaWiki''' and will not work with the older, official releases of MediaWiki like {{MW legacy lts branch number}}; for that, use the <code>{{MW legacy lts release git}}</code> branch (command: <code>git clone -b {{MW legacy lts release git}} <nowiki>https://gerrit.wikimedia.org/r/mediawiki/extensions/VisualEditor.git</nowiki></code>).
* The <code>git submodule update --init</code> command is vital, as VisualEditor MediaWiki extension needs the core VisualEditor submodule to work. '''If you do not use this command, VisualEditor will fail to work'''.
* See [[Parsoid#Development]] for details on linking an alpha build of the Parsoid library up to VisualEditor; the latest version of VisualEditor '''will''' need a development version of Parsoid as well.  '''You must follow the instructions on the {{Mwll|Parsoid}} page to configure Parsoid if you are installing VisualEditor from git, or using an alpha release of 1.36!'''  If you do not, VisualEditor will fail to work.

== Skin compatibility ==
VisualEditor is known to be compatible with the following skins:
* {{Mwll|Skin:Vector|nsp=0}}
* {{Mwll|Skin:MonoBook|nsp=0}}
* {{Mwll|Skin:Timeless|nsp=0}}
* {{Mwll|Skin:Chameleon|nsp=0}}
* {{Mwll|Skin:Apex|nsp=0}}
* {{Mwll|Skin:Poncho|nsp=0}}
* {{Mwll|Skin:Minerva Neue|nsp=0}}
* {{Mwll|Skin:Cosmos|nsp=0}}
* Minerva (was part of {{Mwll|Extension:MobileFrontend|nsp=0}})
* {{Mwll|Skin:Modern|nsp=0}}
* {{Mwll|Skin:Medik|nsp=0}}
* {{Mwll|Skin:Citizen|nsp=0}}
Other skins are not officially supported, but it should be compatible with any skin that uses the required HTML structure – see '''{{Mwll|Extension:VisualEditor/Skin requirements|nsp=0}}'''. Some fiddling with skin stylesheets might be necessary to make everything look nice. It will load on any skin if it matches the feature detection.

== Setting up VisualEditor ==

=== Short URLs on Apache ===
If you are using non-standard short URLs such as <nowiki>"https://wiki.example.org/Page_title"</nowiki> on Apache, you need to [[/Apache rewrite rules for short URLs|adapt the rewrite rules]] for the web server.

VisualEditor will display some broken links if the wiki is not configured with Short Urls. See {{phab|T328337}}.

=== Enabling the write API ===
The user groups who should be able to use VisualEditor must have access to the MediaWiki write API. {{Mwll|Manual:$wgGroupPermissions|$wgGroupPermissions}} needs to be set accordingly, e.g. for the user group named ''user'' this is done with:
<syntaxhighlight lang="php">
$wgGroupPermissions['user']['writeapi'] = true;
</syntaxhighlight>

=== Linking with Parsoid ===
By default VisualEditor is automatically configured to talk to a Parsoid service running on the same host (and on the same port).  '''You should not need to change this in most cases!'''

Some cases when you do need to change the URL of Parsoid:
* Your MediaWiki server is behind a proxy (different remote and local port).
* Your MediaWiki is running inside a docker container with port mapping.
* You want to run Parsoid on a dedicated host or cluster. 

If you need to do this, add the following code to your <code>LocalSettings.php</code> to specify the URL for your Parsoid instance:
<syntaxhighlight lang="php">
$wgVirtualRestConfig['modules']['parsoid'] = array(
    // URL to the Parsoid instance.
    // You should change $wgServer to match the non-local host running Parsoid
    // Note! This is a server to server URL (it must be valid within your VM/container)
    // For a VM or docker this will probably be correct:
    // 'url' => "http://localhost/rest.php",
    'url' => $wgServer . $wgScriptPath . '/rest.php',
    // Parsoid "domain", see below (optional, rarely needed)
    // 'domain' => 'localhost',
);
</syntaxhighlight>

Note that you do not need to the initialise the <code>$wgVirtualRestConfig</code> array anywhere in LocalSettings.

Parsoid's <code>domain</code> setting here must match the host portion of <code>$wgServer</code> on the host running the Parsoid service.

'''If you set <code>$wgVirtualRestConfig['modules']['parsoid']</code> then you will also need to install Parsoid''', either via <code>wfLoadExtension</code> (below) or manually on a separate server or via [[Special:MyLanguage/Parsoid#Linking a developer checkout of Parsoid|the developer instructions on the Parsoid page]].

''Note for developers:'' as noted above, in development releases '''including 1.36-alpha''' Parsoid will need to be manually loaded. This will change before 1.36 is released.  '''If you are running a development release you should follow the instructions in [[Parsoid#Development]]'''—at the very least add the following to your <code>LocalSettings.php</code>:
<syntaxhighlight lang="php">
// For 1.36-alpha and when you changed `wgVirtualRestConfig`:
wfLoadExtension( 'Parsoid', 'vendor/wikimedia/parsoid/extension.json' );
</syntaxhighlight>

=== Allowing VisualEditor on page titles containing slashes ===
If you are serving MediaWiki from apache2, you will need to add the following to your top level server configuration (often a <code>&lt;VirtualHost></code> section in <code>/etc/apache2/sites-enabled/000-default.conf</code> or similar):
<syntaxhighlight lang="apacheconf">
AllowEncodedSlashes NoDecode
</syntaxhighlight>

If you do not, then VisualEditor will complain that "Revision IDs returned by the server do not match" or simply "Error contacting the Parsoid/RESTBase server (HTTP 404)" when editing a page title containing a slash, for example a subpage. See {{MwT|268953}} and the [https://httpd.apache.org/docs/2.4/mod/core.html#allowencodedslashes apache documentation] for more information.

If the Apache server happens to be behind a Nginx proxy then its <code>proxy_pass</code> stanza should make use of the <code>$request_uri</code> parameter (cf. [https://stackoverflow.com/a/20514632 discussion] on StackOverflow).

=== Enabling VisualEditor ===
The following optional configurations can be used:

<syntaxhighlight lang="php">
// Optional: Set VisualEditor as the default editor for anonymous users
// otherwise they will have to switch to VE
$wgDefaultUserOptions['visualeditor-editor'] = "visualeditor";

// Optional: Don't allow users to disable it
$wgHiddenPrefs[] = 'visualeditor-enable';

// Optional: Enable VisualEditor's experimental code features
$wgDefaultUserOptions['visualeditor-enable-experimental'] = 1;

// Activate ONLY the 2017 wikitext editor by default
$wgDefaultUserOptions['visualeditor-autodisable'] = true;
$wgDefaultUserOptions['visualeditor-newwikitext'] = 1;
</syntaxhighlight>
Other extensions which load plugins for VE can be loaded before or after VE; the plugins should work either way.

=== Changing active namespaces ===
By default, VisualEditor is only enabled for the namespaces "Main", "User", "File" and "Category". It is however possible to add or remove namespace using the English language canonical names defined for the respective namespaces such as e.g. "Project", "Talk" etc. Additional custom namespaces use the names used to create them.

<syntaxhighlight lang="php">
// Enable for the meta namespace, disable for the "File" namespace and enable for the "Extra", the latter being a custom namespace
$wgVisualEditorAvailableNamespaces = [
    'Project' => true,
    'File' => false,
    'Extra' => true
];
</syntaxhighlight>

=== Switching between wikitext and visual editing ===
{{MwNote|1=Since MediaWiki 1.40, VisualEditor provides lossless switching between wikitext and visual editing without RESTBase.}}

{{MW version|version=1.39|comment=and before}}
{{MwWarning|1=Do not install RESTBase on a private wiki! RESTBase currently cannot be configured to keep page content private but will make the content of all pages publicly accessible. More details: {{MwT|88016}}}}

VisualEditor allows you to switch back and forth between wikitext and visual editing.

However, without a {{Mwll|RESTBase}} server, switching from wikitext to visual editing may result in ''dirty diffs'' when saving (non-semantic whitespace changes to wikitext formatting). If you want the ability to switch between wikitext editing and VisualEditor and save your changes without dirty diffs, you must install a RESTBase server. 

If you can't set up RESTBase and dirty diffs are undesirable on your wiki (e.g. your users carefully review all changes), you can disable this feature using <code>$wgVisualEditorAllowLossySwitching=false</code>.

When switching isn't possible and you try to switch from a wikitext editing environment into VisualEditor, your only options are ''Cancel'' or ''Discard my changes and switch''; any changes you made will be discarded if you switch.<ref>
[[mailarchive:wikitech-l/2017-February/087635.html]]
</ref>

==== RESTBase setup for switching ====
To set up your own RESTBase service, follow the {{Mwll|RESTBase/Installation|RESTBase installation instructions}}, paying special attention to the Parsoid configuration.

Once the RESTBase server is operational, add the following code to your <code>LocalSettings.php</code>:
<syntaxhighlight lang="php">
$wgVisualEditorParsoidAutoConfig = false;

$wgVirtualRestConfig['modules']['restbase'] = [
  'url' => "http://yourRESTBaseserver.com:7231",
  'domain' => '{domain}',
  'parsoidCompat' => false
];

$wgVisualEditorFullRestbaseURL = 'http://yourRESTBaseserver.com:7231/{domain}/';
</syntaxhighlight>

where <code>{domain}</code> is the value of the host portion of <code>$wgServer</code> on the host running Parsoid. Make sure that the port you specify here (e.g. <code>:7231</code>) is the same port as you specified in the RESTBase configuration.  Be careful to include the trailing slash on <code>$wgVisualEditorFullRestbaseURL</code>!

If you can't access RESTBase port (e.g.<code>:7231</code>),  you can work around the problem using an httpd proxy; refer to "{{Mwll|RESTBase/Installation#If Restbase Port is blocked|if RESTBase port is blocked}}". If your wiki is served through HTTPS, RESTBase must also be served through HTTPS; else users could experience "mixed-content" errors and the switch from wikitext to VisualEditor would not work.

Now when you make changes in a wikitext editor, you can switch to VisualEditor without causing dirty diffs.

{{MwNote|1=In case you are serving your wiki over https, a standard procedure nowadays, you must serve RESTbase via https {{Mwll|Extension:VisualEditor#Parsoid over HTTPS|similarily to Parsoid}} too to avoid [[Topic:Tzq4rg7ixacs2jdr|mixed content errors]]. A concise and easy to understand [[Topic:Tm2qsg4ywsykmahr|discussion of issue is available]]. Do not forget to mix in the following {{Mwll|RESTBase/Installation#RESTBase Server|documentation}}. Remember also to not forget to adapt your port numbers when using stunnel.}}

=== Servers with multiple virtual sites ===
{{MwNote|1=Parsoid is served in production using {{Mwll|Extension:MediaWikiFarm}}.  Running Parsoid on multiple virtual sites using other mechanisms is untested; the instructions below have not been tested.}}

If Apache2 is configured with multiple virtual sites, Parsoid is (in standard configuration) only able to access the default site.  To check for this problem, run <code>curl '<nowiki>[http://your-wiki-base-url</nowiki>]/rest.php/v1/page/Main_Page'</code> on the server, or run <code>curl '<nowiki>[https://your-wiki-base-url</nowiki>]/rest.php/v1/page/Main_Page'</code> ensuring the URL matches the SSL certificate used on the server.

If the response contains the main page of your wiki then you don't have the problem, but if it doesn't, you may need to configure a host alias that Parsoid can use:

Look at the apache2 configuration file for the virtual server hosting the wiki, near the top of the file there should be a line like: 
<blockquote><code><nowiki><VirtualHost *:80></nowiki></code></blockquote>
If the '*' is present, then the alias can be to localhost, if there is an IP address replacing the '*' then the alias must be to that IP address.  
In the same file add a line: <blockquote><code>ServerAlias my_wiki_alias</code></blockquote>

In the hosts file of the server (/etc/hosts on Ubuntu), add a route for my_wiki_alias, either for 127.0.0.1 (if the apache2 virtual server configuration had the '*' above, else to the IP address from the apache2 virtual server configuration.

Now set the hostname in <code>$wgServer</code> to <code>protocol://my_wiki_alias</code> on the host running VisualEditor (see [[Manual:$wgServer]]).

=== Linking with Parsoid in private wikis ===
In a private wiki, you should do this:

; Forwarding cookies to Parsoid
{{MwWarning|1='' ONLY enable this on private wikis served over HTTP and ONLY IF you understand the SECURITY IMPLICATIONS of sending Cookie headers to Parsoid over HTTP!''}}

This is the default configuration for VisualEditor if [[gerrit:q/I0b958e8b75c04e4a27f50f91276be221a5b1404d|not everyone is allowed to read every page]], as such '''the below should not be required in most cases'''.

<syntaxhighlight lang="php">
// Forward users' Cookie: headers to Parsoid. Required for private wikis (login required to read).
// If the wiki is not private (i.e. $wgGroupPermissions['*']['read'] is true) this configuration
// variable will be ignored.
//
// WARNING: ONLY enable this on private wikis and ONLY IF you understand the SECURITY IMPLICATIONS
// of sending Cookie headers to Parsoid over HTTP.
$wgVirtualRestConfig['modules']['parsoid']['forwardCookies'] = true;
</syntaxhighlight>

If you do set any property in <code>$wgVirtualRestConfig['modules']['parsoid']</code> '''you will have to {{Mwll|Parsoid#Linking a developer checkout of Parsoid|manually install Parsoid}} or VisualEditor will not work!'''

{{MwNote
 |For Parsoid/PHP, MediaWiki 1.35.x to 1.38.x using Apache you should try this [[Topic:Vvu2fvadigl0mleu|virtual host configuration]]. Starting with MW 1.39+ it should work out of the box with no extra Apache configuration.
 }}

== Quick configuration guide ==
<div class="noresize">
{| class="wikitable"
! Feature
! Beta Features opt-in state
! Enabled for all to opt-in
! Enabled for all to opt-out
! Enabled for all without opt-out
|-
! Visual mode
| 1.36+:<syntaxhighlight lang="php">
$wgVisualEditorEnableBetaFeature = true;
</syntaxhighlight><1.36:

''Beta Feature shown by default; disable using:''<syntaxhighlight lang="php">
$wgHiddenPrefs[] = 'visualeditor-enable';
</syntaxhighlight>
| <syntaxhighlight lang="php">
$wgDefaultUserOptions['visualeditor-autodisable'] = true;
</syntaxhighlight>
| ''Enabled by default''
| ''As in "Enabled for all to opt-out" plus:''<syntaxhighlight lang="php">
$wgHiddenPrefs[] = 'visualeditor-enable';
</syntaxhighlight>
|-
! Wikitext mode
| <syntaxhighlight lang="php">
$wgVisualEditorEnableWikitextBetaFeature = true;
</syntaxhighlight>
| <syntaxhighlight lang="php">
$wgVisualEditorEnableWikitext = true;
</syntaxhighlight>
| <syntaxhighlight lang="php">
$wgVisualEditorEnableWikitext = true;
$wgDefaultUserOptions['visualeditor-newwikitext'] = 1;
</syntaxhighlight>
| ''As in "Enabled for all to opt-out" plus:''<syntaxhighlight lang="php">
$wgHiddenPrefs[] = 'visualeditor-newwikitext';
</syntaxhighlight>
|-
! Single edit tab
| ''Not a supported configuration.''
| <syntaxhighlight lang="php">
$wgVisualEditorUseSingleEditTab = true;
$wgDefaultUserOptions['visualeditor-tabs'] = 'multi-tab';
</syntaxhighlight>
| <syntaxhighlight lang="php">
$wgVisualEditorUseSingleEditTab = true;
</syntaxhighlight>Default edit tab behaviour will be to remember the last editor, and open with the wikitext editor for first edit; if you want it to be the visual editor, also add:<syntaxhighlight lang="php">
$wgDefaultUserOptions['visualeditor-editor'] = 'visualeditor';
</syntaxhighlight>
| ''As in "Enabled for all to opt-out" plus:''<syntaxhighlight lang="php">
$wgHiddenPrefs[] = 'visualeditor-tabs';
</syntaxhighlight>
|-
! Visual diffs on history pages
| <syntaxhighlight lang="php">
$wgVisualEditorEnableDiffPageBetaFeature = true;
</syntaxhighlight>
| ''Not a supported configuration.''
| ''Not a supported configuration.''
| <syntaxhighlight lang="php">
$wgVisualEditorEnableDiffPage = true;
</syntaxhighlight>
|}
</div>

== Complete list of configuration options ==
Each configuration option is shown without the <code>$wgVisualEditor</code> prefix for brevity; replace the '…' when using.
<div class="noresize">
{| class="wikitable"
! Option
! Default value<!-- As of MW1.30.0-wmf2 -->
! Useful for…
! Documentation
|-
| <code>…PluginModules</code>
| <syntaxhighlight lang="json">
[]
</syntaxhighlight>
| Extension developers
| Array of ResourceLoader module names (strings) that should be loaded when VisualEditor is loaded. Other extensions that extend VisualEditor should add to this array.{{MwWarning|1=When removing a module on a production site (''e.g.'' Wikimedia), first remove it from this array, wait for the change to propagate, and only then remove the module code and module registration. Otherwise there may be a period of time during which VisualEditor depends on a module that no longer exists.}}
|-
| <code>…PreloadModules</code>
| <syntaxhighlight lang="json">
[
    "site",
    "user"
]
</syntaxhighlight>
| Extension developers
| Array of ResourceLoader module names (strings) that should be loaded before VisualEditor is loaded. Other extensions that extend VisualEditor and need to set up their environment before loading should add to this array.{{MwWarning|1=When removing a module on a production site (''e.g.'' Wikimedia), first remove it from this array, wait for the change to propagate, and only then remove the module code and module registration. Otherwise there may be a period of time during which VisualEditor depends on a module that no longer exists.}}
|-
| <code>…PreferenceModules</code>
| <syntaxhighlight lang="json">
{
	"visualeditor-enable-experimental": "ext.visualEditor.experimental"
}
</syntaxhighlight>
| Extension developers
| Associative array of ResourceLoader module names (strings) that should be loaded when VisualEditor is loaded '''if''' the current user has a preference set. Other extensions that extend VisualEditor should add to this array if they want their addition to be opt-in or opt-out. Keys are preference names, values are ResourceLoader module names. 

Remember to also set defaults in <code>$wgDefaultUserOptions</code>!
|-
| <code>…ParsoidAutoConfig</code>
| <syntaxhighlight lang="json">
true
</syntaxhighlight>
| Sysadmins
| Enables auto-configuration of the bundled version of the Parsoid REST API.  Set to <code>false</code> if you have an unusual Parsoid configuration and want to manually configure it.
|-
| <code>…RestbaseURL</code>
| <syntaxhighlight lang="json">
false
</syntaxhighlight>
| Sysadmins
| URL to use to access the main RESTBase call. The page name will be appended directly to this value, so this needs to be set to something like '<code>https://en.wikipedia.org/api/rest_v1/page/html/</code>' <u>including</u> the trailing slash.

If this is set, the page HTML will be requested from RESTBase. If this is not set, the page HTML will be requested from the API, which will send an HTTP request to Parsoid or to RESTBase if available.
|-
| <code>…FullRestbaseURL</code>
| <syntaxhighlight lang="json">
false
</syntaxhighlight>
| Sysadmins
| URL to use to access the rest of RESTBase. The page name will be appended directly to this value, so this needs to be set to something like '<code>https://en.wikipedia.org/api/rest_</code>' <u>excluding</u> the trailing slash.
|-
| <code>…AllowLossySwitching</code>
| <syntaxhighlight lang="json">
true
</syntaxhighlight>
| Sysadmins
| Whether to allow switching from wikitext to visual editor even if doing so may cause dirty diffs. See [[#Switching between wikitext and visual editing]].
|-
| <code>…SerializationCacheTimeout</code>
| <syntaxhighlight lang="json">
3600
</syntaxhighlight>
| Sysadmins
| Serialization cache timeout, in seconds
|-
| <code>…AvailableNamespaces</code>
| <syntaxhighlight lang="php">
[
    "User" => true,
    "File" => true,
    "Category" => true,
    "_merge_strategy" => "array_plus"
]
</syntaxhighlight>
| Sysadmins
| Namespaces in which to enable VisualEditor (mapped from namespace canonical name to a boolean flag), on top of <code>$wgContentNamespaces</code>.
|-
| <code>…AvailableContentModels</code>
| <syntaxhighlight lang="php">
[
    "wikitext" => "article",
    "_merge_strategy" => "array_plus"
]
</syntaxhighlight>
| Extension developers
| Content models in which to enable VisualEditor (mapped from content model name to a boolean flag).
|-
| <code>…UseChangeTagging</code>
| <syntaxhighlight lang="json">
true
</syntaxhighlight>
| Sysadmins
| Whether to put a {{Mwll|Manual:Tags|change tag}} on every edit made with VisualEditor.
|-
| [[#Integration of "2017 wikitext editor"|<code>…EnableWikitext</code>]]
| <syntaxhighlight lang="json">
false
</syntaxhighlight>
| Sysadmins
| Whether to enable the {{Mwll|2017 wikitext editor|wikitext source mode}} inside VisualEditor.
|-
| <code>…EnableDiffPage</code>
| <syntaxhighlight lang="json">
false
</syntaxhighlight>
| Sysadmins
| Whether to enable the {{Mwll|VisualEditor/Diffs|visual diff}} function on the history special page.
|-
| <code>…EnableDiffPageBetaFeature</code>
| <syntaxhighlight lang="json">
false
</syntaxhighlight>
| Sysadmins
| Whether to allow users to enable the {{Mwll|VisualEditor/Diffs|visual diff}} function on the history special page as a beta feature.
|-
| <code>…EnableVisualSectionEditing</code>
| <syntaxhighlight lang="json">
mobile
</syntaxhighlight>
| Sysadmins
| Whether to allow users to enable the section editing.
|-
| <code>…UseSingleEditTab</code>
| <syntaxhighlight lang="json">
false
</syntaxhighlight>
| Sysadmins
| Whether to use only one edit tab, switching back and forth, or add a dedicated VisualEditor edit tab next to the existing one.
|-
| <code>…SingleEditTabSwitchTime</code>
| <syntaxhighlight lang="json">
20160101000000
</syntaxhighlight>
| Sysadmins
| From what timestamp to warn existing editors that the installation has switched from two edit tabs to one. In general you should ignore this.
|-
| <code>…TabPosition</code>
| <syntaxhighlight lang="json">
'before'
</syntaxhighlight>
| Sysadmins
| If showing two edit tabs, where to put the VisualEditor edit tab in relation to the system (or WikiEditor) one:
* 'before': put it right before the old edit tab
* 'after': put it right after the old edit tab
|-
| <code>…TabMessages</code>
| <syntaxhighlight lang="json">
{
	"edit": null,
	"editsource": "visualeditor-ca-editsource",
	"create": null,
	"createsource": "visualeditor-ca-createsource",
	"editlocaldescriptionsource": "visualeditor-ca-editlocaldescriptionsource",
	"createlocaldescriptionsource": "visualeditor-ca-createlocaldescriptionsource",
	"editsection": null,
	"editsectionsource": "visualeditor-ca-editsource-section"
}
</syntaxhighlight>
| Sysadmins
| Configuration of what messages to use for the various kinds of edit tab users can see, if showing two edit tabs:

''''edit'''<nowiki/>' – i18n message key to use for the VisualEditor edit tab; if <code>null</code>, the default edit tab caption will be used; the '<code>visualeditor-ca-ve-edit</code>' message is available for this.

''''editsource'''<nowiki/>' – i18n message key to use for the old edit tab; if <code>null</code>, the tab's caption will not be changed

''''create'''<nowiki/>' – i18n message key to use for the VisualEditor create tab; if <code>null</code>, the default create tab caption will be used; the '<code>visualeditor-ca-ve-create</code>' message is available for this

''''createsource'''<nowiki/>' – i18n message key to use for the old create tab; if <code>null</code>, the tab's caption will not be changed

''''editlocaldescriptionsource'''<nowiki/>' – i18n message key to use for the old edit tab on pages for files in foreign repos; if <code>null</code>, tab's caption will not be changed

''''createlocaldescriptionsource'''<nowiki/>' – i18n message key to use for the old create tab on pages for files in foreign repos; if <code>null</code>, tab's caption will not be changed

''''editsection'''<nowiki/>' – i18n message key to use for the VisualEditor section edit link; if <code>null</code>, the default edit section link caption will be used

''''editsectionsource'''<nowiki/>' – i18n message key to use for the source section edit link; if <code>null</code>, the link's caption will not be changed
|-
| <code>…AutoAccountEnable</code>
| <syntaxhighlight lang="json">
false
</syntaxhighlight>
| Sysadmins
| Whether to enable VisualEditor for every new account.

This allows you to keep the '<code>visualeditor-enable</code>' preference disabled by default, but still have VisualEditor available for new logged-in users (by setting this to <code>true</code>).
|-
| <code>…DisableForAnons</code>
| <syntaxhighlight lang="json">
false
</syntaxhighlight>
| Sysadmins
| Whether to disable VisualEditor for non-logged-in users

This allows you to enable the '<code>visualeditor-enable</code>' preference by default, but still disable VisualEditor for logged-out users (by setting this to <code>true</code>).
|-
| <code>…TransitionDefault</code>
| <syntaxhighlight lang="json">
false
</syntaxhighlight>
| Sysadmins
| For wikis planning to use the '<code>visualeditor-betatempdisable</code>' preference to auto-opt-out existing users whilst enabling by default for all existing users, whether to start recording explicit opt-outs against implicit ones. 
|-
| <code>…ShowBetaWelcome</code>
| <syntaxhighlight lang="json">
true
</syntaxhighlight>
| Sysadmins
| Whether to show the "welcome to the beta" dialog the first time a user uses VisualEditor
|-
| <code>…NewAccountEnableProportion</code>
| <syntaxhighlight lang="json">
false
</syntaxhighlight>
| Sysadmins running user analytics
| Whether to enable VisualEditor for a proportion (Egyptian fraction) of all new accounts based on userID.
|-
| <code>…FeedbackTitle</code>
| <syntaxhighlight lang="json">
false
</syntaxhighlight>
| Sysadmins
| Whether to enable the MediaWiki feedback tool inside the help menu of VisualEditor. If enabled, the title of the page at which to point the MediaWiki feedback tool.
|-
| <code>…FeedbackAPIURL</code>
| <syntaxhighlight lang="json">
false
</syntaxhighlight>
| Sysadmins
| If set, the API of the remote wiki at which to point the MediaWiki feedback tool.
|-
| <code>…SkinToolbarScrollOffset</code>
| <syntaxhighlight lang="json">
[]
</syntaxhighlight>
| Skin developers
| An array of skin names mapped to pixel values to which to set the toolbar scroll offsets.
|-
| <code>…BrowserUnsupportedList</code>
| VisualEditor developers
| List of browsers with which VisualEditor is incompatible. See <code>jquery.Client</code> for specification. If the user's browser is matched, VisualEditor will refuse to load.

'''Firefox''' – There is a wikilink corruption (<code><nowiki>[[./]]</nowiki></code>) bug in Firefox 14 and below ({{MwT|52720}}) which prevent wider availability.

'''Safari''' – Older versions of Safari suffered from corruption issues from various old browser plugins.

'''Opera''' – Below version 12, Opera was untested, and as its user base is almost non-existent anyway it's blocked.

'''Internet Explorer''' – At or below version 9, there are various incompatibilities in layout and feature support. Versions 10 and 11 should work correctly.

Not listed independently, because it's inherited from MediaWiki itself, '''Android''' at 3.x and below "support" CE but don't trigger keyboard input or have other issues, making it useless for users.
|-
| <code>…EnableTocWidget</code>
| <syntaxhighlight lang="json">
false
</syntaxhighlight>
| VisualEditor developers
| Whether to enable the (currently experimental) Table Of Contents widget
|-
| <code>…RebaserURL</code>
| <syntaxhighlight lang="json">
false
</syntaxhighlight>
| VisualEditor developers
| URL to use to access the experimental rebaser technology. If false, the technology isn't loaded.
|}
</div>

=== Related configuration parameters ===
See also [[Upload dialog#Configuration (for wiki sysadmins)]] for information about configuring the drag-and-drop/copy&paste functionality for uploading media files through VisualEditor.

== Integration of "2017 wikitext editor" ==
To enable the so-called "2017 wikitext editor", follow the instructions for '''Wikitext mode''' in the [[EQuick configuration guide]].

It is also possible to enable wikitext syntax highlighting for this editor; to do this, you must install the {{Mwll|Extension:CodeMirror|CodeMirror}} extension.

== Rich template forms ==
{{Mwll|Extension:TemplateData}} allows the addition of template information, making templates easier to insert with the VisualEditor

== Improved citation tool ==
Citations can be improved by configuring the {{Mwll|VisualEditor/Citation tool|citation tool}}, and also by setting up {{Mwll|Citoid}}.

== Hooks ==
As of 2023, Visual Editor sets around 10 JavaScript hooks and 3 PHP hooks that are listed at [[VisualEditor/Hooks]].

== Troubleshooting ==
; All templates appear as puzzle icons instead of displaying its contents
: Check [[Topic:V6tbh7vonvg3mzl9]]

; Docker<nowiki>:</nowiki> Error contacting the Parsoid/RESTBase server (curl error<nowiki>:</nowiki> 7)
: Ensure that the mediawiki container name does not equal to the domain the wiki is running on. If both names are equal, the api will try to connect to the domain the wiki is running on, but only receive the local ip of the container. This will cause errors when ssl is enabled.

;Error contacting the Parsoid/RESTBase server (curl error<nowiki>:</nowiki> 7) Couldn't connect to server
: Ensure that the mediawiki native hostname does not equal to the domain the wiki is running on. If both names are equal, the api will try to connect to the domain the wiki is running on, but will have difficulty resolving the domain.

; Error contacting the Parsoid/RESTBase server<nowiki>:</nowiki> (curl error<nowiki>:</nowiki> 60) Peer certificate cannot be authenticated with given CA certificates
: You may be using a self-signed SSL certificate. Workaround unknown.

; Error contacting the Parsoid/RESTBase server<nowiki>:</nowiki> http-bad-status
:* When editing subpages on Apache, <code>AllowEncodedSlashes NoDecode</code> must be added in the VirtualHost section of the wiki ({{MwT|268953}}).
:* On a HTTP Auth protected wiki, you must allow local access via an allow / geo block in your Apache/Nginx config
:* On a private wiki, see ''"parsoidserver-http-bad-status<nowiki>:</nowiki> 401"'', below

; Error contacting the Parsoid/RESTBase server (HTTP 400)
:* If you are using a Short URL config, check your Nginx/Apache config for <code>/rest.php/?$query_string</code> block – see respective [[Manual:Short_URL#Guides]]
:* An unresolved error for some users. ([[Topic:Wc5hugtg7besmcb2]])

; Error contacting the Parsoid/RESTBase server (HTTP 403)
:* Caused by the 'writeapi' right being revoked (or not granted). Check your LocalSettings.php and remove any overrides for this right. ({{MwT|265043}})
:* Or caused by ModSecurity (or possibly another WAF). Request your hosting service provider to whitelist the security rules that were being triggered by your site. A rule known to cause this is the "missing content-length" check enabled. This rule checks for 'suspicious' but protocol valid behavior. It triggers on multipart POST's and should not be enabled ({{MwT|265043#6866940}})

; Error contacting the Parsoid/RESTBase server (HTTP 404)
: Possible reasons for this problem:
:* Caused by ModSecurity (or possibly another WAF). Request your hosting service provider to whitelist the security rules that were being triggered by your site.
:* When the web server is Apache, <code>AllowEncodedSlashes NoDecode</code> must be added in the VirtualHost section of the wiki ({{MwT|261921}}).
:* Possibly Parsoid is not loaded when using default configuration (local Parsoid, no RestBase). Add to LocalSettings.php: <code>wfLoadExtension( 'Parsoid', 'vendor/wikimedia/parsoid/extension.json' );</code>.
:* If you are using a proxy server or a docker port mapping you will need to set your local url in <code>$wgVirtualRestConfig['modules']['parsoid']</code> (see: [[#Linking with Parsoid]]).
:* Caused by VisualEditor for MW 1.35 and later due to insufficient rewrite rules in case of non-standard short URLs ({{MwT|270376}}). See [[/webserver/]] for the solution.
:* If using [[Manual:Short_URL|short URLs]], place "RewriteCond %{HTTP_USER_AGENT} !^(VisualEditor)" just above "RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} !-f".
:* If you have installed MediaWiki using the Debian <code>mediawiki</code> package, and if the file <code>rest.php</code> is not in your installation path, you are probably missing some new symbolic links (eventually evaluate the command <code>ln -s /var/lib/mediawiki/* .</code> from the installation path to install only the missing ones. In this case, you can ignore the errors about links you aready have)

; Error contacting the Parsoid/RESTBase server (HTTP 415)
: If you're running a private wiki, you might be encountering bug {{MwT|268277}}.
: If you're running a secure site (SSL), but [[Manual:$wgServer|$wgServer]] is set to a protocol-relative URL (<code>//wiki.example.org</code>), you might be encountering bug {{MwT|299175}}.

; Error contacting the Parsoid/RESTBase server (HTTP 500) when saving page with accented character in title, on Windows/IIS
: IIS expects URLs to be encoded using legacy single-byte encodings, but MediaWiki uses UTF-8. Follow these instructions to resolve this: https://support.microsoft.com/en-us/help/2277918/fix-a-php-application-that-depends-on-the-request-uri-server-variable ({{MwT|269673}})

; Error contacting the Parsoid/RESTBase server (HTTP 500) when trying to edit an existing page with VisualEditor
: Persisting in MW 1.35.x . See {{MwT|270377}}

; Error loading data from server<nowiki>:</nowiki> HTTP 500. Would you like to retry?
: Possible reasons for this problem:
:* On new installs, "curl", "php5-curl", or "php7.0-curl" (or other package appropriate to your PHP version) is not installed on the server.
:* setMwApi uri is set incorrectly with e.g. https instead of http.
:* Bad rewrite rules in the apache configuration that would cause API failures.
:* The SSL/TLS certificates are expired.
:* When directory <code>{{Mwll|Manual:$wgTmpDirectory|$wgTmpDirectory}}</code> (for example "/tmp") has not write permissions.
:* When running Windows Authentication with Apache, you would need to white-list 127.0.0.1 in your Apache conf, as Apache doesn't have read access. <syntaxhighlight lang="apache">
<Directory "D:/Wiki/htdocs">
    ...

    Allow from 127.0.0.1
    Satisfy Any
</Directory>
</syntaxhighlight>

; No visible error (Appears to load forever)
: Check the parsoid log file, and consult {{Mwll|Parsoid/Troubleshooting}}.

; parsoidserver-http-bad-status<nowiki>:</nowiki> 401
: Caused by read or edit restrictions (aka 'private wiki'). If you've set up a private wiki and don't want to use cookie forwarding, you can [[mw:User:Andru~mediawikiwiki/Allow Parsoid Server|explicitly remove restrictions for Parsoid by IP address]]. (See [[Topic:Vv35plp6g16qno0s]] and the ticket: [[phab:T268277|MW 1.35.0 "Error contacting the Parsoid/RESTBase server: http-bad-status" on a private wiki]])

; parsoidserver-http-curl-error<nowiki>:</nowiki> couldn't connect to host.
: Parsoid is not running, or <code>$wgVirtualRestConfig['modules']['parsoid']['url']</code> is not set correctly

; parsoidserver-http-curl-error<nowiki>:</nowiki> Failed to connect to ....<nowiki>:</nowiki> Permission denied.
: Can be caused by a cURL request on a [[:en:Security-Enhanced Linux|Security-Enhanced Linux]] (SELinux, like CentOS) to a non standard port like 8000 in the example configuration above, see http://www.akashif.co.uk/php/curl-error-7-failed-to-connect-to-permission-denied and https://www.centos.org/forums/viewtopic.php?f=47&t=53223&p=225372#p225372

; parsoidserver-http-not-acceptable<nowiki>:</nowiki> 406
: Caused by Parsoid 0.9 enforcing clients to return a 1.6.0 and greater HTML version string in the header. This most likely affects Debian users as they are using slightly older MediaWiki versions with MediaWiki's Parsoid APT repository. This can be fixed by either downgrading to 0.8 (not easy as 0.8 no longer exists in the repository) or by editing <code>/usr/lib/parsoid/src/lib/config/ParsoidConfig.js</code> so that <code>ParsoidConfig.prototype.strictAcceptCheck = false;</code>. The latter will be overwritten on any package upgrade, so it is up to the administrator to lock the package and keep on top of updates manually.

; parsoidserver-http-not-found<nowiki>:</nowiki> 404 (or timeout)
: Caused by wrong path to MediaWiki API endpoint. Set correct url to the right path to <code>api.php</code> in Parsoid's <code>localsettings.js</code> config file. If you have set up following the recommendations, your API path would be "http://localhost/w/api.php". Add this API path to "localsettings.js" like "parsoidConfig.setMwApi({uri: 'http://localhost/w/api.php<nowiki/>' });".

; Synology
: Make sure you click the options that engage VisualEditor. If the VE returns an error when you try to save the edited page, this likely means you did not enable zlib (an optional dependency, but required for VE) during installation.
:* Go to: MainMenu (the four little boxes in the left corner of the Synology screen) and choose Web Station
:* In the left sidebar choose <nowiki></></nowiki> Script Language Settings
:* Choose MediaWiki and click Edit and then Extensions
:* At the very bottom of the list, click the zlib box. You will also want to enable the optional dependencies mysql, imagick and zip.

== References ==
<references />

== Development documentation ==
* [[VisualEditor/Gadgets]] - non formal guide for hacking VisualEditor. Includes code snippets and other information useful to gadget authors (and other custom JS devs).
* [https://doc.wikimedia.org/VisualEditor/master/js/ API Documentation] - information on some VisualEditor JS classes.

{{OnWikimedia}}

[[Category:Extensions|VisualEditor]]