Manual: Metadata Block
Clone this wiki locally
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 function.
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.
@id (new in Scriptish!)
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 firstname.lastname@example.org // 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
@grant (improved in Scriptish!)
This is used to grant access to
GM_ functions. If you do not request access to a specific
GM_ function (e.g.
GM_getValue) then it will not be available to your userscript.
// @grant GM_setClipboard // @grant GM_getValue // @grant GM_setValue
Note: In Scriptish (currently not supported by Greasemonkey) you may specify multiple
GM_ functions per
@grant line. For example, you could use the following single line to replace the lines above:
// @grant GM_setClipboard GM_getValue GM_setValue
The original author of the user script, preferably with an e-mail address.
// @author Erik Vold <email@example.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 <firstname.lastname@example.org> 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 <email@example.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.
@homepage or @homepageURL or @website (new in Scriptish!)
A homepage URL for the user script. This is displayed to the user in about:addons.
// @homepageURL http://someplace.com/userscripts/something-wonderful.html
@supportURL (new in Scriptish!)
A support URL, currently not used.
// @supportURL http://github.com/scriptish/scriptish/issues
@updateURL (new in Scriptish!)
An update URL for the user script.
@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.
@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
@icon, @iconURL or @defaulticon (new in Scriptish!)
// @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
@icon64 below for more information on the 64px version.
@icon64 or @icon64URL (new in Scriptish!)
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
@screenshot (new in Scriptish!)
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
@contributionURL (new in Scriptish!)
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
@contributionAmount (new in Scriptish!)
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.
@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 *
@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
// @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.
@run-at (new in Scriptish!)
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
The possible values for
@run-at, in order of occurrence, are:
Runs a script at the start of a page's life cycle.
// @run-at document-start
DOM Ready Injection
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.onload()) event fires.
// @run-at document-idle
Runs a script when the
window.onload() event fires.
// @run-at window-load
@priority (new in Scriptish!)
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
@delay (new in Scriptish!)
Specifies a delay, in milliseconds, before the user script is ran.
// @delay 1000
@resource must have a unique name.
@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
@css (new in Scriptish!)
@css file referenced is downloaded and stored with the userscript on the hard drive, and is automatically applied to pages the userscript executes against. This makes writing CSS easier, separates CSS
GM_addStyle and use of Stylish in combination with Scriptish userscripts fairly redundant.
@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
@jsversion (new in Scriptish!)
@jsversion provided is not acceptable the default (the highest version supported by the user's browser) will be used.
// @jsversion 1.8
@noframes (new in Scriptish!)
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.