Skip to content

Latest commit

 

History

History
309 lines (249 loc) · 10.1 KB

README.org

File metadata and controls

309 lines (249 loc) · 10.1 KB

qutebrowser.el

qutebrowser.el is an Emacs package that provides tight two-way integration between Qutebrowser and EXWM. It provides features such as integration with the Emacs bookmark system, buffer and history sources for Consult, a URL launcher that can be used in place of the default Qutebrowser one, a minor mode for Qutebrowser EXWM buffers, theme synchronization between Emacs and Qutebrowser, and facilities for sending commands and code to Qutebrowser using various backends.

Contents

Features

The currently implemented features are:

  • Remote code/command execution
  • Two-way RPC
  • Hooks for various Qutebrowser events
  • Theme synchronization
  • Bookmarks
  • URL launcher with browsing history completion
  • Password-store autofill
  • REPL for interactively running Python code inside the Qutebrowser process

Planned features

I also plan to implement the following features sometime in the near(ish) future:

  • Combined EXWM modeline and Qutebrowser statusbar. (Under development)
  • Setting keybinds for Qutebrowser commands in an Emacs keymap

Ideas

Some ideas for possible future features. These are not currently planned for implementation, but I keep them around for future use.

  • Integrated searching, synchronizing the searches of search engines, Emacs isearch and similar, and Qutebrowser text searches.
  • Open devtools in an EXWM split.
  • Edit text fields in an EXWM split.
  • URL interceptors for dispatching Emacs commands when URLs matching a pattern is loaded.
  • DWIM on currently open URL. (open youtube in mpv, open code files in Emacs, etc.)
  • A (limited) set of Qutebrowser commands replicated as Emacs commands. This would be a simple convenience wrapper around qutebrowser-send-commands.
  • Option to manage Qutebrowser configurations from Emacs.
  • Integrate with auto-dim-other-buffers-mode to dim inactive Qutebrowser buffers.
  • Some kind of Greasemonkey script handling. Unsure what type of features make sense, and how best to handle things.

Installation

Manual Installation

To install manually, follow these steps:

  1. Clone the repository:
git clone https://github.com/lrustand/qutebrowser.el ~/.emacs.d/site-lisp/qutebrowser.el
  1. Add the following to your Emacs configuration:
(add-to-list 'load-path "~/.emacs.d/site-lisp/qutebrowser.el")
(require 'qutebrowser)

Installation with quelpa

To install using quelpa with use-package, add the following to your Emacs configuration:

(use-package qutebrowser
  :quelpa (qutebrowser :fetcher github
                       :repo "lrustand/qutebrowser.el"
                       :files (:defaults "*.py")))

Prerequisites

  • Qutebrowser: This probably goes without saying.
  • EXWM: Most features are targetting EXWM, and the main aim of the package is to improve usage of Qutebrowser inside EXWM. It should still be possible to get some use out of the package even if you aren’t an EXWM user though.
  • Consult: The URL launcher builds upon Consult and is implemented as Consult buffer sources. The buffer sources can also be added to your consult-buffer-sources to make them available through the consult-buffer command.

Configuration

Recommended Qutebrowser settings

To enable flat web browsing and to make the Consult buffer sources work, Qutebrowser has to be configured to open tabs as windows. It is also recommended to hide the tab bar, since there will be no tabs.

c.tabs.tabs_are_windows = True
c.tabs.show = 'multiple'

If you’re having trouble with existing Qutebrowser windows being raised and given focus when using one of the qutebrowser-launcher commands to open a new window, you might need to add the following line to your config.py:

# Avoid browser being focused when sending commands
c.new_instance_open_target = 'tab-silent'

Despite what the name of the setting might suggest, it does not seem to affect where new windows/tabs are opened, it only keeps from raising the last used window when sending commands using the commandline backend. It might not be necessary to set this option when using the IPC backend.

If you are using the theme synchronization, add this line to your config.py to load the exported theme on Qutebrowser startup:

config.source("emacs_theme.py")

Required Emacs configurations

To be able to use the URL launcher as a userscript, you need to start an Emacs server. Add this to your init.el:

(server-start)

To open a URL in the current buffer through userscripts, Emacs needs the path to the FIFO, which Qutebrowser passes through an environment variable. Unfortunately, emacsclient does not pass on the environment variables to the command it is running, so we make the following small userscript wrapper around emacslient that simply let-binds the environment variable to a local variable before executing the given command:

#!/usr/bin/env bash
emacsclient -e \
  "(let ((qutebrowser-fifo \"$QUTE_FIFO\")
         (qutebrowser-command-backend 'qutebrowser-fifo-send))
     (condition-case nil
         $@
       (t \"\")))" ; true

Because of a bug in emacsclient that causes a delay if a command returns a failure, we also wrap the command in a condition-case.

Usage

Qutebrowser EXWM mode

qutebrowser-exwm-mode can be enabled on a per-buffer basis, or you can enable global-qutebrowser-exwm-mode to automatically enable it in every Qutebrowser buffer.

Currently the mode only activates the bookmark integration, but it can also potentially be used to set keybindings for Qutebrowser buffers.

Bookmarks

When qutebrowser-exwm-mode is active in any buffer, the bookmarking system is automatically set up and can be used just like any other bookmarks through bookmark-set and bookmark-jump (C-x r m and C-x r b by default).

URL launcher

The URL launcher can be used instead of the default by binding it inside Qutebrowser:

config.bind("o", "spawn --userscript emacsclient-wrapper '(qutebrowser-launcher)'")
config.bind("O", "spawn --userscript emacsclient-wrapper '(qutebrowser-launcher-tab)'")
config.bind("wo", "spawn --userscript emacsclient-wrapper '(qutebrowser-launcher-window)'")
config.bind("W", "spawn --userscript emacsclient-wrapper '(qutebrowser-launcher-private)'")
config.bind("go", "spawn --userscript emacsclient-wrapper '(qutebrowser-launcher \"{url:pretty}\")'")
config.bind("gO", "spawn --userscript emacsclient-wrapper '(qutebrowser-launcher-tab \"{url:pretty}\")'")

It can also be used directly from inside Emacs by running one of the interactive commands qutebrowser-launcher, qutebrowswer-launcher-tab, qutebrowser-launcher-window, or qutebrowser-launcher-private.

Qutebrowser command execution

Qutebrowser.el provides the following ways to execute commands and/or code in Qutebrowser:

  • qutebrowser-send-commands: Send Qutebrowser commands such as :open, :back, etc.
  • qutebrowser-execute-js: Execute JavaScript code in Qutebrowser. The code is executed in the same environment as the web page code, making it possible to interact with the web page and any Greasemonkey script that is active there.
  • qutebrowser-execute-python: Execute Python code as if it was written in config.py. Uses :config-source to source a temporary file.
  • qutebrowser-config-source: Sources the given file as a Qutebrowser config file, or reloads config.py if none is given.

Theme synchronization

Enable the theme synchronization by enabling the global minor mode qutebrowser-theme-export-mode. This generates a color scheme for Qutebrowser based on the current Emacs theme any time the Emacs theme changes.

Password store

Username and password autofill can be accomplished by using the qutebrowser-pass command, which can be bound like this:

config.bind(',p', "spawn --userscript emacsclient-wrapper '(qutebrowser-pass \"{url}\")'")
config.bind(',P', "spawn --userscript emacsclient-wrapper '(qutebrowser-pass-password-only \"{url}\")'")
config.bind(',o', "spawn --userscript emacsclient-wrapper '(qutebrowser-pass-otp \"{url}\")'")

Recommended third-party packages

  • vertico-posframe-mode
  • engine-mode