Wikipedia:User scripts/Guide

From Wikipedia, the free encyclopedia
Jump to navigation Jump to search


To write user scripts, you'll have to learn at least some of the programming language that they are written in: JavaScript.

Try these links:

Also, it would definitely help if you tried using one of our scripts and got it working. The rest of this tutorial assumes you know where the various things are (all explained at Wikipedia:User scripts#How do you install user scripts?).

Forking an existing script[edit]

Starting out, it may be easier to modify an existing script to do what you want, rather than create a new script from scratch. This is called "forking". To do this, copy the script to a subpage, ending in ".js",[n. 1] of your user page. Then, install the new page like a normal user script.

Writing a script from scratch[edit]

While you can write a script directly in your common.js page or skin.js (such as vector.js) page, it is usually better to create a new subpage for it in the form YourUserName/title.js, where title is the name of your script. That keeps your main js pages from getting cluttered, which is helpful when you have multiple scripts installed. You will also want to install the new user script.

Your first script[edit]

We will be writing an independent module by modifying your js, so you may want to get our module template. For the purpose of this tutorial, we will write a simple version of the Quick wikify module, so change MODULE_NAME in the module template to "Qwikify". Your template should look like this:

// Qwikify
$(document).ready( function () {
} );

In MODULE_CODE, we want to add the "Wikify" tab, so we will use the addPortletLink function (which requires "mediawiki.util" module). Replace MODULE_CODE with a call to this function. Then we'll bind an event handler so that when this link is clicked, we will call another function named doQwikify() that will actually execute the code. The name is what is shown on the tab, so set that to "Wikify". Most tabs have an id of "ca-(their name)", so set the id to "ca-wikify". The title (also known as mouseover or rollover text) should be something like "Mark for wikification". Lastly, we use jQuery's .click() to listen for clicks on this link, and when that happens execute a function. After we call doQwikify(), it says event.preventDefault(). Since we clicked on a link, we need to tell the browser to prevent its default behavior (which is going to a the url, '#'). We want the page to stay right where it's at, so to prevent the browser from following the link, we prevent that and do our own custom action.

Altogether, your new function should look like this:

// Make sure the utilities module is loaded (will only load if not already)
mw.loader.using( 'mediawiki.util', function () {

    // Wait for the page to be parsed
    $( document ).ready( function () { 

        //see below "Portlets" subsection
        var link = mw.util.addPortletLink( 'p-cactions', '#', 'Wikify', 'ca-wikify', 'Mark for wikification'); 
        $( link ).click( function ( event ) {

        } );
    } );
} );

Now, we must write our actual doQwikify() function. It will edit the edit box, so we need to get the name of that and its form. Viewing the source of the page shows that the form is named editform and the textbox is named wpTextbox1, meaning that the actual text is document.editform.wpTextbox1.value. To add {{wikify}} (and two new lines), we simply do:

document.editform.wpTextbox1.value = "{" + "{wikify}}\n\n" + document.editform.wpTextbox1.value;

(We separate the two "{" brackets in the front of the wikify template so it doesn't get expanded when we write this code on the wiki.)

Finally, we want to submit the form for the user. Luckily, JavaScript has a built-in function just for this named submit(). To submit our editing form, use document.editform.submit(). Your code should now look something like this:

function doQwikify() {
    document.editform.wpTextbox1.value = "{" + "{wikify}}\n\n" + document.editform.wpTextbox1.value;

And that's it! Save the common.js and then do a hard refresh. Go and edit a page (I use the Sandbox) and see what happens![1]

On load/document ready function[edit]

The personal "user" module (build from /common.js, /common.css and optionally the skin-specific files for the current skin) and gadgets are loaded on all pages. Most scripts will want to manipulate elements on the page; to do so the page needs to be ready (which may not be the case at the time the modules are loaded). We can defer execution of code by using a special function. Most commonly .ready() from jQuery.

// Define our main function
function myScript() {
  // ... code ...

// Schedule it to run after the HTML page is parsed
$( document ).ready( myScript );

// This shorthand is also valid
jQuery( myScript );

Since the function is called only once, many users prefer to shorten this code with an anonymous function:

$( document ).ready( function () {
  // ... code ...
} );

// Or
jQuery( function () {
  // ... code ...
} );

Note: $ and jQuery are the same object; choosing between them is purely a matter of opinion.

Many scripts use this function simply to add some script interface, such as a link in a portlet. Then the main part of the code is executed after the user clicks on that link.

Built-in scripts[edit]

All Wikipedia pages include some built-in MediaWiki JavaScript code, with variables and functions that can be used in user scripts. The specific code depends on the viewed page and current users, for more details see Wikipedia:Catalogue of CSS classes#Stylesheets and JavaScript.

Of most interest are:

Writing and testing[edit]

The following methods can be used to test your script.


  • Using the preview button: You can edit your script directly on your /common.js page, then click [Show preview] and the new code is executed right away on the preview page. Note that if you are trying to add a user script to your own installation of MediaWiki software, you will need to open LocalSettings.php and set $wgAllowUserJs: in order to configure your installation to allow user scripts.
$wgAllowUserJs = true;
  • Saving it: If required elements are missing on the preview page (for example, your script does something on history pages), you will have to save the script in order to test it. However, it's not convenient and creates unnecessary entries in the page history.
  • Execute it in your browser's JavaScript console: All modern browsers come with a JavaScript console and other development tools. You can type or paste and execute your code there; script errors and warnings will also be shown there. How to open the console depends on your browser:
    • In Google Chrome and Internet Explorer – press F12
    • In FireFox – press Ctrl-Shift-K
    • In Safari – press Ctrl-Alt-I
    • In Opera – press Ctrl-Shift-I.
You may need to click the Console tab if a different pane is currently open. To execute a multi-line code in Opera, you need to press Ctrl+Enter. For Firefox, you may also want to install the Firebug add-on.

Using a separate local HTML file[edit]

  • Save the Wikipedia page to your local hard drive, including all the corresponding .css and .js files. The specific details depend on your browser.
  • Open saved page in your editor, insert your script code either between <script></script> tags or as a separate local file with <script src="file://C://you_local_path/name.js"></script>.
  • Open the saved page in your browser and preview the result.

This is a very traffic-wise way to quickly develop a user script. However, it has the following disadvantages:

  • the browser will not let you test Ajax queries from a local file
  • you have to save different pages depending on exactly which page (history, etc.) is needed for testing
  • you have to periodically re-save all .js files to synchronize with MediaWiki changes
  • if you want to "casually" test the script while you're browsing Wikipedia, you still have to use other testing methods

Loading it from a localhost web server[edit]

The best and most recommended way to load a JavaScript file during development is from your local web server (see below for an easy way to install a web server). Put this string in your /common.js:

mw.loader.load( 'https://localhost/wikipediatest.js' );

In some environment, you need write this like[2]:

mw.loader.load( '' );

Then run any web server on your computer and create the wikipediatest.js file in the appropriate folder. The code inside this file will be executed as if it was inside your personal script.

You can edit your wikipediatest.js file with any text editor, perhaps with syntax highlighting and other convenient features, save the file and simply reload any Wikipedia page to see the results. (You don't need to wait, and if your web server is nice or you set it right, you don't even need to bypass your browser cache.)

On Windows, you could use for example TinyWeb which is less than 100 kbyte on disk and doesn't require installation. Save and unzip for example into c:\Program Files\Tinyweb, create a shortcut to tiny.exe, and add an argument in shortcut properties — path to your folder with wikipediatest.js and any file index.html (required). Start TinyWeb with this shortcut; unload it with Task Manager.

Note that this method doesn't work in Opera 9.50 (and later) due to added security restrictions, see Opera 9.50 for Windows changelog: "Local servers can use remote resources, but not vice versa". In Chrome, it is also necessary to enable SSL, otherwise the script will refuse to load.


Some browsers allow you to automatically execute your JavaScript code on specific web pages. This way you don't even have to be logged in.

The most famous solution is Logan and equivalents for other browsers.

However, making user scripts work with one of these extensions might require some modifications to the script code.

Some notes for Opera:

  • Placing your script in a corresponding folder as <name>.js file should work for many user scripts.
  • Older versions of Opera (probably below 9.50) did not support UTF-8 local scripts, meaning you could only use Latin characters.

Running pieces of code[edit]

You can run pieces of code on already loaded pages, for example directly in the browser address field: javascript: var s = document.title; alert(s); void 0

Or you can use the bookmarklet «JavaScript Shell». It opens a new browser window where you can paste or type your code and run it in the context of the current page.

However a full-blown JavaScript debugger is much more convenient.


Once you have finished the user script code, you can save it as a page so that others can import it. By convention, scripts are in your userspace and have titles ending in ".js",[n. 1] for example "User:YourUsernameHere/MyCoolScript.js". Others can then install the new script.

Text editors and debugging[edit]

Any text editor will do. If you plan to use non-ASCII characters in string, your text editor should support UTF-8.

Notepad++ is recommended for Windows users, since it can:

  • Highlight JavaScript code
  • Quickly insert standard JavaScript keywords and methods with Ctrl+↵ Enter
  • Show the list of all functions and quickly jump to any function
  • Code folding

Mac OS X users should look into one of these free editors:

Or one of these paid editors:

Most Linux distributions come with a text editor capable of being used for development such as gedit or Kate.

For debugging:

Basic methods[edit]

Finding elements[edit]

Every HTML element is a node in a DOM model which allows scripts to access the element, for example, on the following HTML page.

<form name="frmname" id="frmid">
	<textarea name="txtname" id="txtid"></textarea>
	<input id="neighbor" />

We can find element textarea:

  • Using its id: $( '#txtid' )
  • In the array of all elements with the same tag: $( 'textarea' )
  • Using an element next to it: $( '#neighbor').prev()
  • As a child of its parent: $( '#frmid' ).children( 'form' )
  • As a form element, using name: $( '#frmid [name="txtname"]')

This example on jsFiddle

The jQuery API reference is an excellent source for documentation.

Checking the page[edit]

Many scripts are supposed to work only on some pages. You can check:

  • The page address
if ( mw.config.get( 'wgAction' ) === 'history' ) {  // Continue only on history pages.
  • wg variables; many of them have the same meaning as Magic words
if ( mw.config.get( 'wgCanonicalNamespace' ) === 'User_talk') {  // Continue only on User_talk pages.
  • Presence of elements (only in second and third parts of the script)
function func_start() {
   if ( $( '#editForm' ).length == 0  ) return; //No edit form  ? exit
   // …

Portlets (add custom menus and tabs)[edit]

Usual places to add your own links — portlet blocks with their accompanying id's:

There is a special function in mediawiki.util.js that simplifies the process of adding your own links into portlets:
mw.util.addPortletLink (portlet, href, text, id, tooltip, accesskey, nextnode)

// Several examples of portlet links

// Adds a link to your js file to the toolbox
mw.util.addPortletLink ( 'p-tb', mw.util.getUrl( 'Special:MyPage/common.js' ), 'My JS', 'pt-myvector', 'Visit your js file');

// Add a link to the edit page for your Notes in your personal links
// Note: We assume that short/pretty URLs are in use with ?action, ideally you would check for that.
mw.util.addPortletLink ( 'p-personal', mw.util.getUrl( 'Special:MyPage/Notes' ) + '?action=edit', 'My notes', 'pt-mynotes', 'Edit your personal notes' );

// Adds a link to prefix index for the current page to the toolbox
mw.util.addPortletLink ( 'p-tb', mw.util.getUrl( 'Special:Prefixindex/' + mw.config.get( 'wgPageName' ) ), 'Prefixindex', 'tb-prefixindex');

// Adds a link to logs for your account
mw.util.addPortletLink ( 'p-personal', mw.util.getUrl( 'Special:Log/' + mw.config.get( 'wgUserName' ) ), 'My logs', 'pt-mylogs');
p-logo p-personal name My talk My preferences


p-cactions Article Discussion Read Edit History


 Main page …



Upload file


Portlet structure:

<div id="p-myname" class="portlet">
 <div class="body">
  <li id="…"> <a >  //Links
  <li id="…"> <a >
  … …

Removing elements[edit]

To move an element, simply attach it in another place with .append() or .prepend(). To hide an element, you can simply use .hide().

// Example: remove special characters toolbar from edit page
$( '#editpage-specialchars' ).hide();

// Or modify the CSS directly
$( '#editpage-specialchars' ).css( 'display', 'none' );

This is easier with your CSS though:

#editpage-specialchars {

Text manipulation[edit]

The most important element on the edit page is a <textarea> with the article text inside. You can reference it with

var $textbox = $( '#wpTextbox1' );

You can manipulate it using the jquery.textSelection ResourceLoader module.

var $textbox = $( '#wpTextbox1' );
$textbox.textSelection( 'setContents', 'This is bold!' );
$textbox.textSelection( 'setSelection', { start: 8, end: 12 } );
$textbox.textSelection( 'encapsulateSelection', { pre: '<b>', post: '</b>' } );
// Result: Textbox contains 'This is <b>bold</b>!', with cursor before the '!'


WikiEditor is now the default toolbar when editing the source code of articles, but some users are still using the original toolbar. You can turn on and off WikiEditor by checking and unchecking the "Enable enhanced editing toolbar" check box in your preferences.[n. 4][n. 5]


There is another edit panel under textarea. Usually it's generated from MediaWiki:Edittools by Extension:CharInsert and consists of a lot of JavaScript links. In the English Wikipedia, this approach was replaced by MediaWiki:Gadget-charinsert.js and MediaWiki:Gadget-charinsert-core.js.

Working with CSS[edit]

Some user scripts also use some CSS code, or even are built with CSS only. Then you need to code and test CSS code. That can be done in your /common.css, but it is slow and messy.

Instead, you can load a CSS file from your local web server (see the previous section for an easy-to-install web server). Put this line at the very top of your /common.css:

@import "http://localhost/wikipediatest.css";

Note! Such @import statements must come before any other declarations in your CSS. But there can be /* comments */ above them.

An alternative way is to put this line anywhere in your css instead:

mw.loader.load( 'http://localhost/wikipediatest.css', 'text/css' );

Publishing a CSS file[edit]

Once you have finished the CSS code, you either need to paste it into your /vector.css if it is only for personal use. Or if it is for use by others then you should upload it to for instance User:Yourname/yourscript.css. Then other users can import it by putting the following line in their /common.js file. Note, that is in their ".js", not their ".css".

importStylesheet( 'User:Yourname/yourscript.css' );

If the CSS should be used together with a user script written in JavaScript then you can make it easy for the users. Simply put the line above in the JavaScript code for your user script, then the users only need to "install" your JavaScript.

For completeness, in case someone wonders, users can import your User:Yourname/yourscript.css from their /common.css too. This of course has the advantage that it works even if the user has JavaScript disabled. Although it takes this slightly complex line of code:

@import "/w/index.php?title=User:Yourname/yourscript.css&action=raw&ctype=text/css";


AJAX (asynchronous JavaScript and XML) is a popular name for a web programming technique that queries the server or fetches content without reloading the entire page.

While programming AJAX can be complex, libraries of functions can make it much easier. Since the 1.16 release, MediaWiki comes with the jQuery library, which provides a convenient framework for easily making Ajax requests.

Common problems[edit]

  • AJAX programmers commonly run into problems if they don't account for AJAX's asynchronicity. If you try to pop up a box with another page's content, you will almost certainly pop up a box containing null. This occurs because the script continued even though the query wasn't finished.

    To correct the problem, you need to use callback functions. Place the next portion of code after a query into a function, and call the function when the query completes. jQuery makes this very easy to do.

  • AJAX scripts cannot reach a page on a different server (for example, or from Trying to do so will cause the script to halt with or without error. This can be circumvented using a proxy on the current server, but none is available for Wikimedia user scripts.

Basic examples[edit]

MediaWiki provides some modules with helper functions which facilitate the use of its API. The main modules available are

If your script makes use any method or code provided by these modules, remember to indicate the dependencies with mw.loader.using or, in case of gadgets, on its definition at MediaWiki:Gadgets-definition.

This API has several advantages especially when dealing with POST requests. It provides automatic token refresh and retry, handles various error situations and does parameter request building for several common use cases like rolling back a revision.

Fetch page content[edit]

Fetching a page content can be done using GET.

	url: mw.util.getUrl( 'Wikipedia:Sandbox' )
.done(function( data ) {
	alert( 'The remote page contains:\n' + data );
.fail(function() {
	alert( 'The ajax request failed.' );

Get the wikitext of a page[edit]

Using module mediawiki.api[edit]

Note: make sure to add "mediawiki.api" to your dependencies!

function doSomethingWithText( wikitext ) {
	/* .. */
	alert( 'The wikitext of the page is:\n\n' + wikitext );
function doSomethingInCaseOfError () {
	/* .. */
	console.log( 'err' );
(new mw.Api()).get( {
	prop: 'revisions',
	rvprop: 'content',
	rvlimit: 1,
	indexpageids: true,
	titles: 'Wikipedia:Sandbox'
} )
.done( function ( data ) {
	var q = data.query,
		id = q && q.pageids && q.pageids[0],
		pg = id && q.pages && q.pages[ id ],
		rv = pg && pg.revisions;
	if ( rv && rv[0] && rv[0]['*'] ) {
		doSomethingWithText( rv[0]['*'] );
} )
.fail( doSomethingInCaseOfError );
Using plain jQuery[edit]
		format: 'json',
		action: 'query',
		prop: 'revisions',
		rvprop: 'content',
		rvlimit: 1,
		titles: 'Wikipedia:Sandbox'
	.done(function ( data ) {
		var page, wikitext;
		try {
			for ( page in data.query.pages ) {
				wikitext = data.query.pages[page].revisions[0]['*'];
				doSomethingWithText( wikitext );
		} catch ( e ) {
	.fail( doSomethingInCaseOfError );

Edit a page and other common actions[edit]

Scripts can perform common actions (like editing, protection, blocking, deletion, etc.) through the API. These actions require an edit token, which is valid for any action during the same session. (However, you should get a new token for different tasks in case this changes in the future.)

The code below shows how to edit a page, but it can easily be adapted to other actions by reading the API documentation.

// Edit page (must be done through POST)
// the line "text: info.text," will cause the call 
// to replace entire page content with supplied data.
// alternatively, one can append or prepend the data to the page, by using
// "appendtext: info.text," or "prependtext: info.text," instead.
// when using "appendtext", it is possible to append the text to a specific section,
// by setting the optional field "section".
function editPage( info ) {
		url: mw.util.wikiScript( 'api' ),
		type: 'POST',
		dataType: 'json',
		data: {
			format: 'json',
			action: 'edit',
			title: info.title,
			text: info.text, // will replace entire page content
			summary: info.summary,
			token: mw.user.tokens.get( 'editToken' )
	.done (function( data ) {
		if ( data && data.edit && data.edit.result && data.edit.result == 'Success' ) {
			alert( 'Page edited!' );
		} else {
			alert( 'The edit query returned an error. =(' );
	.fail ( function() {
		alert( 'The ajax request failed.' );
	title: 'User:' + mw.config.get( 'wgUserName' ) + '/Sandbox',
	text: 'Cool! It works! :-) ~~' + '~~',
	summary: 'Trying to edit my sandbox [[Project:User scripts/Guide/Ajax|using AJAX]]...'

See also[edit]


  1. ^ a b The actual requirement is that the page have contentmodel "javascript". Making a page whose title ends in ".js" will automatically give it that content model and indicates to readers that the page contains JavaScript.
  2. ^ Firebug is strongly recommended for convenient debugging.
  3. ^ Dragonfly is strongly recommended for convenient debugging.
  4. ^ See mw:Extension:WikiEditor/Toolbar customization for information on how to customize WikiEditor.
  5. ^ See User:V111P/js/addToolbarButtons for a script which allows you to easily add buttons to whichever of the two toolbars the user is using.


  1. ^ This section originally written by raylu my monobook.js Thanks a ton to all the users who helped improve this tutorial!
  2. ^
  3. ^