If the metadata block includes a key that Greasemonkey does not understand, it will simply be ignored. Some authors choose to include their own keys, and userscripts.org defines a set of metadata keys for varying purposes.
It is important to note that all of the information specified in the metadata block is parsed and loaded at install time only. Although script authors may edit the source of a user script on the fly, and see these changes reflected upon the next execution of the script, metadata is not reloaded upon every execution. To change the metadata Greasemonkey uses, the script must be reinstalled.
The metadata block must follow the format:
// ==UserScript== // @key value // ==/UserScript==
It must use line comments (
//) like above, not block comments (
Some keys may have multiple values.
In all cases the key and value(s) are separated by whitespace.
// @name Example Script
The name of the script. This appears in the script manager and monkey menu, and is also the unique identifier of a script (within a #@namespace). If no name is provided, it will be derived from the file name.
// @namespace http://www.example.com/gmscripts
The combination of namespace and name is the unique identifier for a Greasemonkey script. If a script is being installed, and a script with that same name and namespace already exists, it will be replaced by the new script. Otherwise, the new script is added to the set of installed scripts. A script author will usually put all of their scripts under one common namespace, and then assign each script a unique name.
While the namespace is non-semantic, a URL is often used. Some authors use the common home page for the collection of scripts they have written. But remember, the namespace can be any unique value.
// @description This script even does the laundry!
Just a brief summary of what the script does, presented to the user as the script is installed, and in the manage dialog.
// @include http://www.example.com/* // @include http://* // @include *
See Include and exclude rules. There can be any number of @include rules in a script.
Examples: see @include above
See Include and exclude rules. There can be any number of @exclude rules in a script.
- Compatibility: Greasemonkey 0.8.0+
// @resource resourceName http://www.example.com/example.png
There can be any number of @resource keys in a script.
Each @resource is downloaded once, when the script is installed, and stored on the user's hard drive alongside the script. The URL specified may be relative to the URL the script is being installed from.
Compatibility: Greasemonkey 0.8.0+
// @require http://www.example.com/example.js
There can be any number of @require keys in a script. Each @require is downloaded once, when the script is installed, and stored on the user's hard drive alongside the script. The URL specified may be relative to the URL the script is being installed from.
Compatibility: Greasemonkey 0.8.1+
This declarative key has no associated value. It changes the interpretation of the script as it executes.
Normally, greasemonkey scripts are wrapped in an anonymous function when they are executed. This behavior started in very early versions of greasemonkey, which ran scripts directly in the content page, to separate their variables from those in the page. In later versions, it remains because isolating the script from the sandbox scope still helps in certain cases.
This key is strongly recommended to only be used for debugging purposes.
// ==UserScript== // @name My Script // @namespace http://www.example.com/gmscripts // @description Scripting is fun // @include http://www.example.com/* // @include http://www.example.org/* // @exclude http://www.example.org/foo // @require foo.js // @resource resourceName1 resource1.png // @resource resourceName2 http://www.example.com/resource2.png // ==/UserScript==