Quick-start Guide
Using Luakit
If you've used browsers like vimperator, or vimium, you'll find yourself right at home; most if not all luakit actions are available via keyboard commands.
Just run:
luakit [URI..]
Or to see the full list of luakit launch options run:
luakit -h
Opening the help page
To open the internal help page, press <F1>
. From there, you can open
the introspector to view current keybindings or open the included API
documentation.
Switching to command mode
Many common operations in luakit, such as typing and opening a URL, involve the
use of commands. This is done by switching to command mode, typing the
command, and pressing <Enter>
.
To switch to command mode, press :
(i.e. <Shift-;>
), and the command
bar will appear at the bottom of the window. In the remainder of this document,
commands will be written prefixed by a :
; so :open
means to first press
:
, and then type open
.
Go to a URL in the current tab
Type :open
followed by a space and the URL to navigate to, and press <Enter>
.
For example, to open the luakit website, type :open luakit.github.io
and then
press press <Enter>
.
Shortcut: press o
to switch to command mode with open
already typed.
Search
Press /
, and type your search query, e.g: /luakit
. Press <Enter>
to finish typing your search query and switch back to normal mode.
While in normal mode with highlighted search results, press n
to
jump to the next search result, and N
to jump to the previous one.
Opening, closing, and undo-closing tabs
Try the following steps in order:
- Run
:tabopen luakit.org
, and wait until the page finishes loading. - Press
d
, and the new tab will close. - Press
u
, and the just-closed tab will reappear.
Scrolling in a web page
There are several different keys to scroll a webview:
- The arrow, page up/down, and home/end keys all work as one would expect.
- The
h
,j
,k
,l
,gg
, andG
key bindings all scroll in a vim-like manner. - The
<Control-e>
,<Control-y>
,<Control-d>
,<Control-u>
,<Control-f>
, and<Control-b>
keys all scroll vertically by various amounts.
Bookmarks
- Press
B
to bookmark the current page. - Press
gb
orgB
to open the bookmarks page in the current tab or a new tab, respectively.
Configuration
It is possible to configure most of the global Luakit settings in the luakit://settings page. For further adjustments (per-domain settings, adjusting/defining bindings or commands) you should create a custom configuration file.
Beginning a custom configuration
To customize luakit, you can define your own configuration by creating a
userconf.lua
file in the ~/.config/luakit/
directory. This file
is loaded automatically by luakit, if it exists. Any changes made to it will
take effect after restarting luakit.
Changing key bindings
To add/remove key bindings, use add_binds
and remove_binds
methods from the modes
module to do so. For example, the following code
re-binds <Control-c>
so the selected text gets copied to the clipboard:
--- userconf.lua local modes = require "modes" modes.add_binds("normal", {{ "<Control-c>", "Copy selected text.", function () luakit.selection.clipboard = luakit.selection.primary end }})
If you just want to re-map an existing action to a new keybinding, you can use
the remap_binds
method. For example:
-- maps "<Control-p>" to the same action as "gT" (go to previous tab), and -- keeps "gT" binded as well modes.remap_binds("normal", { {"<Control-p>", "gT", true} })
You can also check all the currently available key bindings in the luakit://binds page, for each of luakit's modes, along with their documentation and links to the exact location where they were defined.
Changing the theme
Apart from rc.lua
, the other configuration file is theme.lua
, which
specifies the fonts and colours used by the interface widgets.
Location of configuration files
When looking for a .lua
file by name, luakit checks the following locations,
in the order specified here:
- The current directory.
- System directories for Lua files.
- Luakit's collection of included modules (
/usr/share/luakit/lib/
). - The user's personal luakit configuration directory (
~/.config/luakit/
). - The system configuration directories (
/etc/xdg/luakit/
).
To list the directories luakit will search when loading modules, run the following command:
:lua w:notify(package.path:gsub(";","\n"))