ce8d15d2b0
It was broken at least since caret support was introduced and it was only available for QtWebKit anyways, so let's just drop it. This also makes the tab API a bit simpler.
87 lines
3.1 KiB
Plaintext
87 lines
3.1 KiB
Plaintext
Writing qutebrowser userscripts
|
|
===============================
|
|
The Compiler <mail@qutebrowser.org>
|
|
|
|
qutebrowser is extensible by writing userscripts which can be called via the
|
|
`:spawn --userscript` command, or via a key binding.
|
|
|
|
You can also call a userscript via hints so they get the selected hint URL by
|
|
calling `:hint links userscript ...`.
|
|
|
|
These userscripts are similar to the (non-javascript) dwb userscripts. They can
|
|
be written in any language which can read environment variables and write to a
|
|
FIFO. Note they are *not* related to Greasemonkey userscripts.
|
|
|
|
Note for simple things such as opening the current page with another browser or
|
|
mpv, a simple key binding to something like `:spawn mpv {url}` should suffice.
|
|
|
|
Also note userscripts need to have the executable bit set (`chmod +x`) for
|
|
qutebrowser to run them.
|
|
|
|
To call a userscript, it needs to be stored in your data directory under
|
|
`userscripts` (for example: `~/.local/share/qutebrowser/userscripts/myscript`),
|
|
or just use an absolute path.
|
|
|
|
NOTE: On Windows, only userscripts with `com`, `bat`, or `exe` extensions will be launched.
|
|
|
|
Getting information
|
|
-------------------
|
|
|
|
The following environment variables will be set when a userscript is launched:
|
|
|
|
- `QUTE_MODE`: Either `hints` (started via hints) or `command` (started via
|
|
command or key binding).
|
|
- `QUTE_USER_AGENT`: The currently set user agent, if customized.
|
|
- `QUTE_FIFO`: The FIFO or file to write commands to.
|
|
- `QUTE_HTML`: Path of a file containing the HTML source of the current page.
|
|
- `QUTE_TEXT`: Path of a file containing the plaintext of the current page.
|
|
- `QUTE_CONFIG_DIR`: Path of the directory containing qutebrowser's configuration.
|
|
- `QUTE_DATA_DIR`: Path of the directory containing qutebrowser's data.
|
|
- `QUTE_DOWNLOAD_DIR`: Path of the downloads directory.
|
|
- `QUTE_COMMANDLINE_TEXT`: Text currently in qutebrowser's command line.
|
|
|
|
In `command` mode:
|
|
|
|
- `QUTE_URL`: The current URL.
|
|
- `QUTE_TITLE`: The title of the current page.
|
|
- `QUTE_SELECTED_TEXT`: The text currently selected on the page.
|
|
|
|
In `hints` mode:
|
|
|
|
- `QUTE_URL`: The URL selected via hints.
|
|
- `QUTE_SELECTED_TEXT`: The plain text of the element selected via hints.
|
|
- `QUTE_SELECTED_HTML` The HTML of the element selected via hints.
|
|
|
|
Sending commands
|
|
----------------
|
|
|
|
Normal qutebrowser commands can be written to `$QUTE_FIFO` and will be
|
|
executed.
|
|
|
|
On Unix/macOS, this is a named pipe and commands written to it will get executed
|
|
immediately.
|
|
|
|
On Windows, this is a regular file, and the commands in it will be executed as
|
|
soon as your userscript terminates. This means when writing multiple commands,
|
|
you should append to the file (`>>` in bash) rather than overwrite it (`>`).
|
|
|
|
Examples
|
|
--------
|
|
|
|
Opening the currently selected word on http://www.dict.cc/[dict.cc]:
|
|
|
|
[source,bash]
|
|
----
|
|
#!/bin/bash
|
|
|
|
echo "open -t http://www.dict.cc/?s=$QUTE_SELECTED_TEXT" >> "$QUTE_FIFO"
|
|
----
|
|
|
|
Libraries
|
|
---------
|
|
|
|
Some third-party libraries are available to make writing userscripts easier:
|
|
|
|
- Python: https://github.com/hiway/python-qutescript[python-qutescript]
|
|
- Node.js: https://www.npmjs.com/package/qutejs[qutejs]
|