2.2. Describing your user script with metadata [Dive Into Greasemonkey]

2.2. Describing your user script with metadata

Every user script has a section of metadata that tells Greasemonkey about the script itself, where it came from, and when to run it.

Example: Hello World metadata

// ==UserScript==
// @name          Hello World
// @namespace     http://diveintogreasemonkey.org/download/
// @description   example script to alert "Hello world!" on every page
// @include       *
// @exclude       http://diveintogreasemonkey.org/*
// @exclude       http://www.diveintogreasemonkey.org/*
// ==/UserScript==

There are six separate pieces of metadata here, wrapped in a set of Greasemonkey-specific comments. Let's take them in order, starting with the wrapper.

// ==UserScript==
//
// ==/UserScript==

These comments are significant, and must match exactly. Greasemonkey uses them to signal the start and end of your user script metadata. This section may be defined anywhere in your script, but is usually near the top.

Within the Greasemonkey metadata section, the first item is the name.

// @name          Hello World

This is the name of your user script. It is displayed in the install dialog when you first install the script, and later in the “Manage User Scripts” dialog. It should be short and to the point.

@name is optional. If present, it may appear only once. If not present, it defaults to the filename of the user script, minus the .user.js extension.

Next comes the namespace.

// @namespace     http://diveintogreasemonkey.org/download/

This is a URL, and Greasemonkey uses it to distinguish user scripts that have the same name but are written by different authors. If you have a domain name, you can use it (or a subdirectory) as your namespace. Otherwise you can use a tag: URI.

@namespace is optional. If present, it may appear only once. If not present, it defaults to the domain from which the user downloaded the user script.

You can specify the items of your user script metadata in any order. I like @name, @namespace, @description, @include, and finally @exclude, but there is nothing special about this order.

Next comes the description.

// @description   example script to alert "Hello world!" on every page

This is a human-readable description of what the user script does. It is displayed in the install dialog when you first install the script, and later in the “Manage User Scripts” dialog. It should be no more than two sentences.

@description is optional. If present, it may appear only once. If not present, it defaults to an empty string.

Don't forget the @description. Even if you are only writing user scripts for yourself, you will eventually end up with dozens of them, and administering them all in the “Manage User Scripts” dialog will be much more difficult if you don't include a description.

The next three lines are the most important items (from Greasemonkey's perspective): the @include and @exclude URLs.

// @include       *
// @exclude       http://diveintogreasemonkey.org/*
// @exclude       http://www.diveintogreasemonkey.org/*

These lines tell Greasemonkey on which sites you want your user script to execute. Both specify a URL, with the * character as a simple wildcard for part of the domain name or path. In this case, we are telling Greasemonkey to execute the Hello World script on all sites except http://diveintogreasemonkey.org/ and http://www.diveintogreasemonkey.org/. Excludes take precedence over includes, so even though http://diveintogreasemonkey.org/download/ matches * (all sites), it will be excluded because it also matches http://diveintogreasemonkey.org/*.

@include and @exclude are optional. You may specify as many included and excluded URLs as you need, but you must specify each on its own line. If neither is specified, Greasemonkey will execute your user script on all sites (as if you had specified @include *).

You need to be very specific with your @include and @exclude metadata. Greasemonkey makes no assumptions about URLs that an end user might consider equivalent. If a site responds on both http://example.com/ and http://www.example.com/, you need to declare both variations.

Dive Into Greasemonkey

2.2. Describing your user script with metadata

Example: Hello World metadata

Further reading