Manual: Metadata Block
The metadata block of a user script must have the following format:
// ==UserScript==
// @key value_1 value_2 value_etc
// ==/UserScript==
It must use line comments //
and not block comments /* */
. If a key has multiple values, those values must be space-separated. The metadata block must be within the // ==UserScript==
starting line and the // ==/UserScript==
ending line.
Note: You can access your script's metadata at runtime with the GM_getMetadata API.
Scriptish strives to support all @keys provided by other user script engines. If there are any @keys you would like to see supported in Scriptish please create an issue (if one doesn't already exist).
Note: Unlike other user script engines, Scriptish @keys are not case sensitive.
The id, a unique identifier, for the user script. Scriptish will use the id to distinguish different user scripts, e.g. when loading script user preferences (See about:config). Also, the id might be displayed in the error/web console as a prefix to error messages generated by user scripts.
// @id its-a-wonderful-userscript@someplace.com
// or
// @id plainoldtextstring
The name of a user script. This is displayed to users in the Scriptish toolbar menu and in about:addons.
// @name A Wonderful Script
This is used by other user script engines, in combination with @name, to create a unique identifier. Since Scriptish uses @id this is not currently used, but is still suggested as a possible way to group user scripts.
// @namespace http://someplace.com
This is used to grant access to GM_
APIs, if you do not request access to an API then you will not get it.
// @grant GM_setClipboard
The original author of the user script, preferably with an e-mail address.
// @author Erik Vold <evold@mozilla.com> http://work.erikvold.com/
Note: We strongly recommend you use the format below, as it allows Scriptish to provide a better experience when presenting your user script in the Firefox Add-ons Manager.
// @author Fname MNames LName <email@company.com> http://website-url.com/
The names of co-developers for the user script.
// @developer Super Coder
A contributor to the user script.
// @contributor Mary Jane <admin@420.com>
The user script's version. This is displayed to the user in about:addons.
Note: User scripts should specify their versions using the Toolkit version format.
// @version 2.0
A description of the user script. This is displayed to the user in about:addons.
// @description This user script kicks ass by applying boot to booty.
A homepage URL for the user script. This is displayed to the user in about:addons.
// @homepageURL http://someplace.com/userscripts/something-wonderful.html
A support URL, currently not used.
// @supportURL http://github.com/scriptish/scriptish/issues
An update URL for the user script.
The @updateURL
must be secure (i.e. a https://
URL) unless the "Require user scripts to update using HTTPS" option (Scriptish Options -> Advanced -> Update Security) is set.
Note: @version
is required when using @updateURL
, and it must use the Toolkit version format.
Note: If the @updateURL
points to a .meta.js
file, Scriptish will check that for updates. If it is determined a new script version is available, Scriptish will look for a .user.js
file with the same file name, domain, and path. A .meta.js
is typically used instead of the .user.js
file to save bandwidth and improve response time.
// @updateURL https://somedomain.com/downloads/cool-script.meta.js
An icon URL for the user script. This is displayed to the user in notifications made through GM_notification and in about:addons. The value can be a URL to an image, or a data:
URL for an image.
// @icon http://someplace.com/img/kickass.png
Note: a 64px version of the icon can be provided following the icon URL, like so:
// @icon http://someplace.com/img/kickass.png http://someplace.com/img/kickass64.png
See @icon64
below for more information on the 64px version.
A 64px icon URL for the user script. This is displayed to the user in a user script's details page within about:addons. The value can be a URL to an image, or a data:
URL for an image.
// @icon64 http://someplace.com/img/kickass64.png
A screenshot URL for the user script. Multiple @screenshot keys are allowed. The image may be of any type that you could use on a website. You may also, optionally, provide a thumbnail version of the image as @screenshot's second value.
// @screenshot http://something.com/some/path/img.jpg http://something.com/some/path/thumb.jpg
// @screenshot http://something.com/some/path/img.jpg
URL of a page to load if a user wishes to make a monetary contribution. This will be displayed in the user script's "More" page, accessible from the User Scripts list in the Add-ons Manager.
// @contributionURL https://m.e/donations
A suggested contribution amount. If @contributionURL
is set, this will be displayed in the user script's "More" page, accessible from the User Scripts list in the Add-ons Manager.
Note: @contributionAmount
is optional; only the @contributionURL
is required for the contribution message to appear.
// @contributionAmount $1.00
### @domain *(new in Scriptish!)*
Describes the domain name(s) a user script is allowed to run on and access through GM_xmlhttpRequest. If @domain is not defined, it is assumed the user script needs access to all domains. Multiple @domain keys are allowed.
Note: Explicitly stating the domain name(s) your user script needs to access is highly recommended, since it will provide your users with a better understanding of your script.
// @domain google.com
// @domain www.google.com
Describes the URL range on which the user script should run. Multiple @include keys are allowed.
// @include http://www.example.com/*
// @include http://*
// @include *
Note: @include
may also be a regular expression literal, but only the i
flag is recognized (for case-insensitivity).
// @include /^https?:\/\/(?:www\.)?google\.com\/something\//i
This comes from Google Chrome user scripts, and is a stricter version of @include. See Google Chrome's documentation on Match Patterns for further details.
// @match http://*
// @match http://*.google.com/*
// @match http://www.google.com/*
Describes the URL range to exclude (even if the page is @include'd). The value format is the same as @include.
This idea comes from the Google Chrome user script documentation (but was implemented first by Scriptish), and specifies when Scriptish will run user scripts. Scriptish (and Greasemonkey) load scripts on document-end
by default, whereas Google Chrome defaults to document-idle
.
The possible values for @run-at
, in order of occurrence, are: document-start
, document-end
, document-idle
and window-load
.
Runs a script at the start of a page's life cycle.
// @run-at document-start
Runs a script when the DOMContentLoaded
event fires.
// @run-at document-end
Runs a script some time between document-end
and immediately after the window-load
(i.e. window.onload()
) event fires.
// @run-at document-idle
Runs a script when the window.onload()
event fires.
// @run-at window-load
Specifies a script's priority level. The greater the number the greater the priority. If two or more scripts have the same @run-at
value, then @priority
will determine the execution order (scripts are also delayed in this order).
// @priority 1 // higher priority
// @priority -1 // lower priority
// @priority -100 // very low priority
// @priority 0 // default value
Specifies a delay, in milliseconds, before the user script is ran.
// @delay 1000
The resourceName value (see example below) must comply with JavaScript identifier restrictions. Each @resource must have a unique name.
Each @resource
is downloaded during the user script installation and stored on the user's hard drive in the same folder as the script. The @resource URL may be relative to the user script's download location.
// @resource resourceName http://www.example.com/example.png
// @resource resourceName2 /example2.png
// @resource css /styles.css
GM_addStyle(GM_getResourceText('css'))
Each @css
file referred to is downloaded and stored with the userscript on the hard drive and is automatically applied to pages that the userscript is applied to. This makes writing css easier, separates css
from javascript making both easier to read, and renders GM_addStyle
and using Stylish in combination with Scriptish userscripts fairly redundant.
Each @require
is downloaded during the user script installation and stored on the hard drive in the same folder as the script. The @require URL may be relative to the user script's download location.
// @require http://www.someplace.com/tools.js
// @require /tools2.js
Specifies the version of JavaScript the user script was built to work on and, if supported, will be run on. If the @jsversion provided is not acceptable the default (the highest version supported by the user's browser) will be used.
// @jsversion 1.8
If this key exists the user script will not run in iframes.
No value should be given for @noframes. If a value is provided the line will be ignored.
// @noframes