What is Witchcraft?

Think Greasemonkey for developers.

Witchcraft is a Google Chrome extension for loading custom Javascript and CSS directly from a folder in your file system, injecting them into pages that match their files names.

It works by matching the current page domain against script file names available in the scripts folder. For instance, if one navigates to https://www.google.com, Witchcraft will try to load and run google.com.js and google.com.css. For the screenshot above, those are:

Actual practical uses include getting rid of nasty ads, automating clicks and improving page layouts with your own CSS rules. You're only limited by what Javascript and CSS can do.

Main features

• Javascript and CSS injection

  Witchcraft is not only able to run Javascript, but also CSS;

• Script changes are seamless

  Whenever you edit or create new scripts, there's no need to reload anything other than the page where the scripts are supposed to run. This is what makes Witchcraft special and different from other popular scripting tools, like Greasemonkey or Tampermonkey;

• Cross-platform

  Since Witchcraft runs as a Chrome extension, it is also cross-platform. It has been tested on Windows, MacOS and Linux;

• Runs on all frames

  Witchcraft is listening for pages loading everywhere, not just on the top frame. This means it will run even on pages loaded inside other pages.

How to use

Once your environment is ready (see installation instructions), simply start creating your scripts and adding them to the scripts folder. If you'd like to run some script every time you enter, say, github.com, just go ahead and create github.com.js. Then head to github.com (or refresh the page if it's already open) and the script will run immediately.

Domain level scripts

Witchcraft also looks for scripts on all domain levels. For instance, if one accesses https://gist.github.com, it will try to load all domain levels for which there are existing scripts, in this very order:

• _global.js (see next section for more details)
• _global.css (see next section for more details)
• com.js
• com.css
• github.com.js
• github.com.css
• gist.github.com.js
• gist.github.com.css

Every script found is directly executed in the current page's context.

Global scripts

If present, _global.js and _global.css scripts (added in version 2.3.0) will load for every web site, independently of the host name. Useful if you have some setup routine common to all your scripts.

Path segments

Starting with version 2.5.0, Witchcraft also tries to match path segments. For example, going to https://github.com/luciopaiva/witchcraft will yield the following sequence of script loading attempts:

• _global.js
• _global.css
• com.js
• com.css
• github.com.js
• github.com.css
• github.com/luciopaiva.js
• github.com/luciopaiva.css
• github.com/luciopaiva/witchcraft.js
• github.com/luciopaiva/witchcraft.css

Notice that path segments are mapped to local folders in your scripts directory.

Also important to notice is that, if the host name begins with www, it must be part of the directory structure as well. This is important because modern browsers tend to hide the www part, giving the false impression that it is not there.

Including other scripts

It's possible to include scripts from your main JavaScript or CSS file via the @include directive. To use it, simply add a special one-line comment like so:

You may add multiple directives to the same script. If your script name contains spaces, you can use double quotes to refer to it (see the JavaScript example above).

It is possible to include remote scripts as well:

Useful for loading scripts from gists, for example.

Included scripts can also @include scripts of their own; the parser will recursively iterate through them. Dependency cycles (e.g., foo.js includes bar.js, which includes foo.js) will be automatically resolved and each script won't be loaded more than once.

This directive may be useful for including third-party libraries, like jQuery.