Version 4
Nyxt Manual
Core concepts
#
Core concepts
#
Keybindings and commands
#
Keybindings and commands
#
Commands are invoked by pressing specific keys or from the
execute-command
(
M-x
)
.
Keybindings are represented like this: 'C-x'. In this example, 'C' is a shortcut for the modifier 'control', and 'x' represents the character 'x'. To input the 'C-x' keybinding you would keep 'control' pressed and then hit 'x'. Multiple key presses can be chained: in 'C-x C-s', you would have to press 'C-x', and then press 'C-s'.
Modifier keys legend:
-
control(C): Control key -
super(S): Windows key, Command key -
meta(M): Alt key, Option key -
shift(s): Shift key
Modifiers can be remapped, see slot
modifier-plist
.
Quickstart keys
#
Quickstart keys
#-
set-url ( C-l ): Set the URL for the current buffer, completing with history. -
reload-current-buffer ( C-r ): Reload current buffer. -
set-url-new-buffer ( M-l ): -
switch-buffer-previous ( C-x C-left ): Switch to the previous buffer. -
history-backwards ( C-b ): Navigate backwards. -
history-forwards ( C-f ): Navigate forwards. -
follow-hint ( M-g ): Follow the top element hint selection in the current buffer. -
follow-hint-new-buffer ( M-s-g ): Like `follow-hint', but selection is handled in background buffers. -
quit ( C-x C-c ): Quit Nyxt. -
execute-command ( M-x ): Execute a command by name. -
describe-bindings ( C-h b ): Show a list of all available keybindings in the current buffer.
Buffers
#
Buffers
#Nyxt uses the concept of buffers instead of tabs. Unlike tabs, buffers are fully separated, each buffer having its own behavior and settings.
Modes
#
Modes
#Each buffer has its own list of modes, ordered by priority. A mode is a set of functions, hooks, keybindings and other facilities that may modify the behavior of a buffer. For example, 'blocker-mode' drops requests to the hosts it lists, while 'no-image-mode' disables images.
Each buffer has separate instances of modes, which means that altering the settings of a mode in a buffer does not impact other buffers. Mode specific functions/commands are only available when a mode is enabled for the current buffer.
Each mode has an associated mode toggler which is a command of the same name that toggles the mode for the current buffer.
Prompt buffer
#
Prompt buffer
#
The prompt buffer is a menu that will appear when a command requests user input.
For example, when invoking the
set-url
command, you must supply the URL you would like to navigate to. The prompt
buffer can provide suggestions. The list of suggestions will automatically
narrow down to those matching your input as you type.
-
run-action-on-return ( keypadenter ): Validate the selected suggestion(s) or the current input if there is no suggestion. -
set-action-on-return ( M-keypadenter ): Query the user for an action to run over the marked suggestion(s).
Some commands support marks, for instance
delete-buffer
can delete all selected buffers at once. When the input is changed and the
suggestions are re-filtered, the marks are not altered even if the marked
suggestions aren't visible.
When at least one suggestion is marked, only the marked suggestions are processed upon return. The suggestion under the cursor is not processed if not marked.
-
toggle-mark-forwards ( C-keypadenter ): Select or deselect the current suggestion. -
mark-all ( M-a ): Select all currently-displayed suggestions. -
unmark-all ( M-u ): Deselect all currently-displayed suggestions. -
toggle-mark-all ( M-m ): Toggle the mark of all currently-displayed suggestions. -
toggle-attributes-display ( C-] ): Change which attributes are displayed in the suggestions list.
Message buffer
#
Message buffer
#
The message buffer represents a space (typically at the bottom of a window)
where Nyxt outputs messages back to you. To view the history of all messages,
invoke the command
list-messages
(
unbound
)
.
Status buffer
#
Status buffer
#The status buffer is where information about the state of that buffer is printed (typically at the bottom of a window). By default, this includes the active modes, the URL, and the title of the current buffer.
Basic controls
#
Basic controls
#
Moving within a buffer
#
Moving within a buffer
#To move within a buffer, several commands are provided:
-
scroll-down ( C-n ): Scroll down the current page. -
scroll-up ( C-p ): Scroll up the current page. -
scroll-page-down ( C-v ): Scroll down by one page height. -
scroll-page-up ( M-v ): Scroll up by one page height. -
scroll-to-bottom ( M-s-. ): Scroll to the bottom of the current page. -
scroll-to-top ( M-s-, ): Scroll to the top of the current page.
Setting the URL
#
Setting the URL
#When ambiguous URLs are inputted, Nyxt will attempt the best guess it can. If you do not supply a protocol in a URL, HTTPS will be assumed. To visit a site supporting only the less secure HTTP, you must explicitly type the full URL including the 'http://' prefix.
-
set-url ( C-l ): Set the URL for the current buffer, completing with history. -
set-url-new-buffer ( M-l ): -
make-buffer-focus ( C-t ): Switch to a new buffer.
Switching buffers
#
Switching buffers
#-
switch-buffer ( C-x b ): Switch buffer using fuzzy completion. -
switch-buffer-next ( C-x C-right ): Switch to the next buffer. -
switch-buffer-previous ( C-x C-left ): Switch to the previous buffer.
Copy and paste
#
Copy and paste
#Unlike other web browsers, Nyxt provides powerful ways of copying and pasting content via different commands. Starting from:
-
copy ( M-w ): Copy selected text to clipboard. -
paste ( C-y ): Paste from clipboard into active element.
Passing through webpage's data:
-
copy-url ( C-M-l ): Save current URL to clipboard. -
copy-title ( C-M-t ): Save current page title to clipboard. -
copy-hint-url ( C-x C-w ): Save the element hint's URL to the clipboard.
Leveraging password managers:
-
copy-username ( unbound ): Query username and save to clipboard. -
copy-password ( unbound ): Query password and save to clipboard.
And more:
-
paste-from-clipboard-ring ( M-y ): Show `*browser*' clipboard ring and paste selected entry. -
show-system-information ( unbound ): Display information about the currently running Nyxt system.
Incremental Search
#
Incremental Search
#Nyxt's search is incremental, i.e. it begins as soon as you type the first character of the search string. A single or multiple buffers can be queried, and all results are displayed in the prompt buffer.
This makes it easy to interact with results found in different URLs from a unified interface.
-
search-buffer ( C-s s ): Search incrementally on the current buffer. -
search-buffers ( unbound ): Search incrementally in multiple buffers. -
remove-search-marks ( C-s k ): Remove all search marks.
Bookmarks
#
Bookmarks
#
The bookmark file
is made to be human readable and editable. Bookmarks can have the following
settings:
-
:url: The URL of the bookmark. -
:title: The title of the bookmark. -
:tags: A list of strings. Useful to categorize and filter bookmarks.
Bookmark-related commands
-
add-bookmark ( C-x r l ): Prompt for objects to bookmark. -
bookmark-hint ( C-m g ): Prompt for element hints and bookmark them. -
set-url-from-bookmark ( C-x r j ): Set the URL for the current buffer from a bookmark. -
edit-bookmark ( unbound ): Edit bookmark(s). -
delete-bookmark ( C-x r k ): Delete bookmark(s) matching the chosen URLS-OR-BOOKMARK-ENTRIES. -
list-bookmarks ( unbound ): List all bookmarks in a new buffer. -
import-bookmarks-from-html ( unbound ): Import bookmarks from an HTML-FILE with bookmarks from other browsers.
Annotations
#
Annotations
#Annotations can have the following settings:
-
snippet: The snippet which was highlighted by the user. -
url: The URL of the annotation. -
page-title: The title of the annotation. -
data: The comment about the highlighted snippet or the URL. -
tags: A list of strings. Useful to categorize and filter annotations.
Annotate-related commands
-
annotate-current-url ( unbound ): Create an annotation of the URL of BUFFER. -
annotate-highlighted-text ( unbound ): Create an annotation for the highlighted text of BUFFER. -
edit-annotation ( unbound ): Edit annotation(s). -
delete-annotation ( unbound ): Delete annotation(s). -
show-annotation ( unbound ): Show prompted annotations. -
show-annotations ( unbound ): Show all annotations. -
show-annotations-for-current-url ( unbound ): Create a new buffer with the annotations of the current URL of BUFFER.
Passthrough mode
#
Passthrough mode
#
The command
passthrough-mode
forwards all keys to the renderer. For instance, using the default binding of
Nyxt (
web-cua-map
) the keybinding
C-i
executes
autofill
. Suppose a user is using their email client which also uses
C-i
for the italic command. Thus, after executing
passthrough-mode
the
C-i
binding is associated with the webpage's italic command instead of
autofill
. Finally, the user can return to their configuration just by executing
passthrough-mode
again.
Enable, disable, and toggle multiple modes
#
Enable, disable, and toggle multiple modes
#
The command
enable-modes
(
unbound
)
allows the user to apply multiple modes (such as
nosound-mode
and
dark-mode
) to multiple buffers at once. Conversely, it is possible to revert this action
by executing
disable-modes
(
unbound
)
while choosing exactly the same buffers and modes previously selected. Finally,
toggle-mode
also allows activation and deactivation of multiple modes, but only for the
current buffer.
Spelling check
#
Spelling check
#
Several commands are provided to spell check words. The default is English but
it is possible to change the slot
spell-check-language
for other languages:
-
spell-check-word ( M-s-4 ): Spell check a word. -
spell-check-word-at-cursor ( unbound ): Spell check the word at the cursor. -
spell-check-suggest-word ( unbound ): Suggest a spelling for a given word. -
spell-check-highlighted-word ( unbound ): Spell check a highlighted word. -
spell-check-list-languages ( unbound ): List all languages supported on your machine.
Visual mode
#
Visual mode
#
Select text without a mouse. Nyxt's
visual-mode
imitates Vim's visual mode (and comes with the CUA and Emacs-like
keybindings out of the box, too). Activate it with the
visual-mode
(
unbound
)
command.
Visual mode provides the following commands:
-
visual-mode ( C-c ): Quit visual mode. -
select-paragraph ( unbound ): Add hints to text elements on the page and query them. -
toggle-mark ( unbound ): Toggle the mark. -
forward-char ( right ): Move caret forward by a character. -
backward-char ( backspace ): Move caret backward by a character. -
forward-word ( unbound ): Move caret forward by a word. -
backward-word ( unbound ): Move caret backward by a word. -
forward-line ( down ): Move caret forward by a line. -
backward-line ( up ): Move caret backward by a line. -
beginning-line ( keypadhome ): Move caret to the beginning of the line. -
end-line ( keypadend ): Move caret to the end of the line. -
forward-sentence ( unbound ): Move caret forward to next end of sentence. -
backward-sentence ( unbound ): Move caret backward to start of sentence.
Commands designed to ease the use for CUA users (but available to all users):
-
forward-char-with-selection ( s-right ): Set mark and move caret forward by a character. -
backward-char-with-selection ( s-left ): Set mark and move caret backward by a character. -
forward-line-with-selection ( s-down ): Set mark and move caret forward by a line. -
backward-line-with-selection ( s-up ): Set mark and move caret backward by a line.
A note for
emacs-mode
users: unlike in Emacs, in Nyxt the command
toggle-mark
(
unbound
)
is bound to Shift-space, as C-space is bound to 'execute-command.
Automation
#
Automation
#Nyxt has many facilities for automation. For instance, it is possible to automate the reading experience:
-
cruise-control-mode ( unbound ): Toggle `cruise-control-mode'.
Symmetrically, it is possible to automate the filling of forms:
-
autofill ( C-i ): Fill in a field with a value from a saved list. -
toggle-checkboxes ( unbound ): Toggle all checkboxes.
In addition, it is possible to automate actions over time:
-
repeat-every ( unbound ): Prompt for function to be run every seconds.
Or even automate actions based on conditions:
-
repeat-mode ( unbound ): Toggle `repeat-mode'.
Lastly, the
process-mode
must be highlighted:
process-mode
is actually a building block for other modes previously mentioned, such as
repeat-mode
. The extension relationship goes further, since
cruise-control-mode
is in its turn an extension and a composition of
repeat-mode
and
scroll-down
(
C-n
)
. Further extensions and compositions can be creatively tailor-made by users to
automate their own use of Nyxt.
Miscellaneous
#
Miscellaneous
#-
zoom-page ( C-x C-= ): Zoom in the current page. -
unzoom-page ( C-x C-hyphen ): Zoom out the current page. -
reset-page-zoom ( C-x C-0 ): Reset the current page zoom to 0. -
autofill ( C-i ): Fill in a field with a value from a saved list. -
download-open-file ( unbound ): Open file in Nyxt or externally. -
edit-with-external-editor ( C-u C-x C-f ): Edit the current input field using `external-editor-program'.
The Nyxt help system
#
The Nyxt help system
#Nyxt provides introspective and help capabilities. All commands, classes, slots, variables, functions and bindings can be inspected for definition and documentation.
-
tutorial ( C-h t ): Display Nyxt tutorial. -
describe-key ( C-h k ): Display binding of user-inputted keys. -
describe-bindings ( C-h b ): Show a list of all available keybindings in the current buffer. -
describe-command ( C-h c ): Inspect a command and show it in a help buffer. -
describe-function ( C-h f ): Inspect a function and show it in a help buffer. -
describe-variable ( C-h v ): Inspect a variable and show it in a help buffer. -
describe-class ( C-h s-c ): Inspect a class and show it in a help buffer. -
describe-slot ( C-h s ): Inspect a slot and show it in a help buffer. -
describe-any ( C-h a ): Inspect anything and show it in a help buffer.
A good starting point is to study the documentation of the classes
browser
,
window
,
buffer
and
prompt-buffer
.
Configuration
#
Configuration
#Nyxt is written in the Common Lisp programming language which offers a great perk: everything in the browser can be customized by the user, even while it's running!
To get started with Common Lisp, we recommend checking out our web page: Learn Lisp . It contains numerous pointers to other resources, including free books both for beginners and seasoned programmers.
Settings created by Nyxt are stored in
/home/doe/.config/nyxt/auto-config.4.lisp
.
Any settings can be overridden manually by
/home/doe/.config/nyxt/config.lisp
.
The following section assumes knowledge of basic Common Lisp or a similar programming language.
The user needs to manually create the Nyxt configuration file, and the parent folders if necessary.
You can also press the button below to create it.
Example:
(define-configurationweb-buffer ((default-modes(pushnew'nyxt/mode/no-sound:no-sound-mode%slot-value%))))
The above turns on the 'no-sound-mode' (disables sound) by default for every buffer.
The
define-configuration
macro can be used to customize the slots of classes like the browser, buffers,
windows, etc.
To find out about all modes known to Nyxt, run
describe-command
(
C-h c
)
and type 'mode'.
Different types of buffers
#
Different types of buffers
#
There are multiple buffer classes, such as
document-buffer
(for structured documents) and
input-buffer
(for buffers that can receive user input). A
web-buffer
class is used for web pages,
prompt-buffer
for, well, the prompt buffer. Some buffer classes may inherit from multiple
other classes. For instance
web-buffer
and
prompt-buffer
both inherit from
input-buffer
.
You can configure one of the parent
buffer
classes slots and the new values will automatically cascade down as a new
default for all child classes- unless this slot is specialized by these child
classes.
Keybinding configuration
#
Keybinding configuration
#
Nyxt supports multiple
bindings schemes
such as CUA (the default), Emacs or vi. Changing scheme is as simple as setting
the corresponding mode as default, e.g.
emacs-mode
. To make the change persistent across sessions, add the following to your
configuration:
-
vi bindings:
(
define-configurationinput-buffer ((default-modes(pushnew'nyxt/mode/vi:vi-normal-mode%slot-value%)))) -
Emacs bindings:
(
define-configurationinput-buffer ((default-modes(pushnew'nyxt/mode/emacs:emacs-mode%slot-value%))))
You can create new scheme names with
make-keyscheme
. Also see the
define-keyscheme-map macro
.
To extend the bindings of a specific mode, you can configure the mode with
define-configuration
and extend its
keyscheme-map
with
define-keyscheme-map
. For example:
(define-configurationbase-mode "Note the :import part of thedefine-keyscheme-map. It re-uses the other keymap (in this case, the one that was slot value before the configuration) and merely adds/modifies it." ((keyscheme-map(define-keyscheme-map"my-base" (list:import%slot-value%)keyscheme:vi-normal(list"g b" (lambda-commandswitch-buffer* nil (switch-buffer:current-is-last-p t)))))))
The
nothing
(
C-g
)
command is useful to override bindings to do nothing. Note that it's
possible to bind any command, including those of disabled modes that are not
listed in
execute-command
(
M-x
)
. Binding to
nothing
(
C-g
)
and binding to NIL means different things (see the documentation of
define-key
for details):
-
nothing ( C-g ) - Binds the key to a command that does nothing. Still discovers the key and recognizes it as pressed.
- NIL
- Un-binds the key, removing all the bindings that it had in a given mode/keyscheme-map. If you press the un-bound key, the bindings that used to be there will not be found anymore, and the key will be forwarded to the renderer.
- Any other symbol/command
- Replaces the command that was there before, with the new one. When the key is pressed, the new command will fire instead of the old one.
In addition, a more flexible approach is to create your own mode with your custom keybindings. When this mode is added first to the buffer mode list, its keybindings have priorities over the other modes. Note that this kind of global keymaps also have priority over regular character insertion, so you should probably not bind anything without modifiers in such a keymap.
(defvar*my-keymap* (nkeymaps/core:make-keymap"my-map")) (define-key*my-keymap* "C-f" 'nyxt/mode/history:history-forwards "C-b" 'nyxt/mode/history:history-backwards) (define-modemy-mode nil "Dummy mode for the custom key bindings in*my-keymap*." ((keyscheme-map(nkeymaps/core:make-keyscheme-mapkeyscheme:cua*my-keymap*keyscheme:emacs*my-keymap*keyscheme:vi-normal*my-keymap*)))) (define-configurationweb-buffer "Enable this mode by default." ((default-modes(pushnew'my-mode%slot-value%))))
Bindings are subject to various translations as per
*translator*
.
By default if it fails to find a binding it tries again with inverted shifts.
For instance if
C-x C-F
fails to match anything
C-x C-f
is tried.
See the default value of
*translator*
to learn how to customize it or set it to
nil
to disable all forms of translation.
Search engines
#
Search engines
#The following search engines are defined, where the default one is the first:
(mapcar#'make-instance'(ddg-search-engine wikipedia-search-engine))
The
:shortcut
parameter above impacts the behavior of commands such as
set-url
(
C-l
)
. For example, typing
foo
or
ddg foo
both results in querying DuckDuckGo for
foo
(meaning that the shortcut may be omitted when using the default search
engine). As you might have guessed,
wiki foo
queries Wikipedia instead.
The example below exemplifies how to define additional search engines:
(defvar*my-search-engines* (list(make-instance'search-engine:name "Google" :shortcut "goo" :control-url "https://duckduckgo.com/?q=~a") (make-instance'search-engine:name "MDN" :shortcut "mdn" :control-url "https://developer.mozilla.org/en-US/search?q=~a"))) (define-configurationbrowser ((search-engines(append%slot-default%*my-search-engines*))))
Note that the default search engine is determined by
default-search-engine
(by default, the first element of
search-engines
). Therefore, the order of arguments passed to
append
in the code snippet above is key.
For more information on the topic see
search-engine
.
History
#
History
#Nyxt history model is a vector whose elements are URLs.
History can be navigated with the arrow keys in the status buffer, or with
commands like
history-backwards
(
C-b
)
and
history-forwards
(
C-f
)
(which the arrows are bound to).
Downloads
#
Downloads
#
See the
list-downloads
(
C-d
)
command and the
download-path
buffer slot documentation.
URL-dispatchers
#
URL-dispatchers
#
You can configure which actions to take depending on the URL to be loaded. For
instance, you can configure which Torrent program to start to load magnet links.
See the
url-dispatching-handler
function documentation.
Custom commands
#
Custom commands
#
Creating your own invocable commands is similar to creating a Common Lisp
function, except the form is
define-command
instead of
defun
. If you want this command to be invocable outside of the context of a mode, use
define-command-global
.
Example:
(define-command-globalmy-bookmark-url nil "Query which URL to bookmark." (let ((url (prompt:prompt "Bookmark URL" :sources 'prompter:raw-source))) (nyxt/mode/bookmark:persist-bookmarkurl)))
See the
prompt-buffer
class documentation for how to write custom prompt buffers.
You can also create your own context menu entries binding those to Lisp
commands, using
ffi-add-context-menu-command
function. You can bind the
bookmark-url
like this:
(ffi-add-context-menu-command 'my-bookmark-url "Bookmark URL")
Currently, context menu commands don't have access to the renderer objects
(and shouldn't hope to). Commands you bind to context menu actions should
deduce most of the information from their surroundings, using JavaScript and
Lisp functions Nyxt provides. For example, one can use the
url-at-point
to get thep URL currently under pointer.
With this, one can improve the bookmarking using
url-at-point
:
(ffi-add-context-menu-command(lambda () (nyxt/mode/bookmark:persist-bookmark(url-at-point(current-buffer)))) "Bookmark Link")
Custom URL schemes
#
Custom URL schemes
#Nyxt can register custom schemes that run a handler on URL load.
The example below defines a scheme
hello
that replies accordingly when loading URLs
hello:world
and
hello:mars
.
(define-internal-scheme"hello" (lambda (url) (if(string=(quri.uri:uri-path(urlurl)) "world") (spinneret:with-html-string(:p "Hello, World!")) (spinneret:with-html-string(:p "Please instruct me on how to greet you!")))))
Note that scheme privileges, such as enabling the Fetch API or enabling CORS requests are renderer-specific.
nyxt: URLs and internal pages
#
nyxt: URLs and internal pages
#You can create pages out of Lisp commands, and make arbitrary computations for the content of those. More so: these pages can invoke Lisp commands on demand, be it on button click or on some page event. The macros and functions to look at are:
-
define-internal-pageto create new pages. -
buffer-load-internal-page-focusto either get or create the buffer for the page. -
nyxt-urlto reference the internal pages by their name. -
define-internal-page-commandto generate a mode-specific command loading the internal page. -
define-internal-page-command-globalto generate a global command loading the internal page.
Using the facilities Nyxt provides, you can make a random number generator page:
(define-internal-page-command-globalrandom-number (&key (max 1000000)) (buffer "*Random*") "Generates a random number on every reload." (spinneret:with-html-string(:h1 (princ-to-string (random max))) (:button.button :onclick (parenscript:ps (nyxt/parenscript:lisp-eval (:title "re-load/re-generate the random number") (ffi-buffer-reload buffer))) :title "Re-generate the random number again" "New number")))
Several things to notice here:
-
Internal page command is much like a regular command in being a Lisp function
that you can call either from the REPL or from the
execute-command ( M-x )menu. -
With one important restriction: internal page commands should only have keyword
arguments. Other argument types are not supported. This is to make them
invocable through the URL they are assigned. For example, when you invoke the
random-numbercommand you've written, you'll see thenyxt:nyxt-user:random-number?max=%1B1000000URL in the status buffer. The keyword argument is being seamlessly translated into a URL query parameter. - There's yet another important restriction: the values you provide to the internal page command should be serializable to URLs. Which restricts the arguments to numbers, symbols, and strings, for instance.
- Those commands should return the content of the page in their body, like internal schemes do.
-
If you want to return HTML, then
with-html-stringis your best friend, but no one restricts you from producing HTML in any other way, including simply writing it by hand ;) -
nyxt/ps:lisp-evalis a Parenscript macro to request Nyxt to run arbitrary code. The signature is:((&key (buffer '(nyxt:current-buffer)) title) &body body). You can bind it to a<button>'sonClickevent, for example.
If you're making an extension, you might find other macros more useful.
define-internal-page-command
, for example, defines a command to only be visible when in the corresponding
mode is enabled. Useful to separate the context-specific commands from the
universally useful (
-global
) ones. If there's a page that you'd rather not have a command for, you
can still define it as:
(define-internal-page not-a-command
nil
(:title "*Hello*" :page-mode 'base-mode)
"Hello there!")
and use as:
(buffer-load-internal-page-focus 'not-a-command)
See the slots and documentation of
internal-page
to understand what you can pass to
define-internal-page
.
Hooks
#
Hooks
#Hooks provide a powerful mechanism to tweak the behavior of various events that occur in the context of windows, buffers, modes, etc.
A hook holds a list of handlers . Handlers are named and typed functions. Each hook has a dedicated handler constructor.
Hooks can be 'run', that is, their handlers are run according to the
combination
slot of the hook. This combination is a function of the handlers. Depending on
the combination, a hook can run the handlers either in parallel, or in order
until one fails, or even
compose
them (pass the result of one as the input of the next). The handler types
specify which input and output values are expected.
To add or delete a hook, you only need to know a couple of functions:
-
handlera class to wrap hook handlers in. -
add-hook(also known ashooks:add-hook) allows you to add a handler to a hook,for it to be invoked when the hook fires. -
nhooks:on(also available ashooks:on) as a shorthand for thenhooks:add-hook. -
remove-hook(also available ashooks:remove-hook) that removes the handler from a certain hook. -
nhooks:once-on(also available ashooks:once-on) as a one-shot version ofnhooks:onthat removes the handler right after it's completed.
Many hooks are executed at different points in Nyxt, among others:
-
Global hooks, such as
after-init-hookorafter-startup-hook. - Window- or buffer-related hooks.
-
window-make-hookfor when a new window is created. -
window-delete-hookfor when a window is deleted. -
window-set-buffer-hookfor when thecurrent-bufferchanges in the window. -
buffer-load-hookfor when there's a new page loading in the buffer. -
buffer-loaded-hookfor when this page is mostly done loading (some scripts/image/styles may not be fully loaded yet, so you may need to wait a bit after it fires.) -
request-resource-hookfor when a new request happens. Allows redirecting and blocking requests, and is a good place to do something conditioned on the links being loaded. -
prompt-buffer-ready-hookfires when the prompt buffer is ready for user input. You may need to callall-ready-pon the prompt to ensure all the sources it contains are ready too, and then you can safely set new inputs and select the necessary suggestions. - Commands :before and :after methods.
-
Try, for example,
(defmethod set-url :after (&key (default-action nil)) ...)to do something after the set-url finishes executing. - Modes 'enable' and 'disable' methods and their :before, :after, and :around methods.
-
Mode-specific hooks, like
before-download-hookandafter-download-hookfordownload.
For instance, if you want to force 'old.reddit.com' over 'www.reddit.com', you can set a hook like the following in your configuration file:
(defunold-reddit-handler (request-data) (let ((url(urlrequest-data))) (setf (urlrequest-data) (if(search"reddit.com" (quri.uri:uri-hosturl)) (progn (setf (quri.uri:uri-hosturl) "old.reddit.com") (log:info"Switching to old Reddit: ~s" (render-urlurl)) url) url))) request-data) (define-configurationweb-buffer ((request-resource-hook(sera:add-hook%slot-default%'old-reddit-handler))))
(See
url-dispatching-handler
for a simpler way to achieve the same result.)
Or, if you want to set multiple handlers at once,
(define-configurationweb-buffer ((request-resource-hook(reduce#'sera:add-hook'(old-reddit-handler auto-proxy-handler) :initial-value%slot-default%))))
Some hooks like the above example expect a return value, so it's important
to make sure we return
request-data
here. See the documentation of the respective hooks for more details.
Password management
#
Password management
#
Nyxt provides a uniform interface to some password managers including
KeepassXC
and
Password Store
.
The supported installed password manager is automatically detected.
See the
password-interface
buffer slot for customization.
You may use the
define-configuration
macro with any of the password interfaces to configure them. Please make sure
to use the package prefixed class name/slot designators within the
define-configuration
.
-
save-new-password ( unbound ): Query for name and new password to persist in the database. -
copy-password ( unbound ): Query password and save to clipboard.
KeePassXC support
#
KeePassXC support
#The interface for KeePassXC should cover most use-cases for KeePassXC, as it supports password database locking with
-
master-password, -
key-file, -
and
yubikey-slot
To configure KeePassXC interface, you might need to add something like this snippet to your config:
(defmethodinitialize-instance :after ((interface password:keepassxc-interface) &key &allow-other-keys) "It's obviously not recommended to set master password here, as your config is likely unencrypted and can reveal your password to someone peeking at the screen." (setf (password:password-fileinterface) "/path/to/your/passwords.kdbx" (password:key-fileinterface) "/path/to/your/keyfile" (password:yubikey-slotinterface) "1:1111")) (define-configurationnyxt/mode/password:password-mode ((nyxt/mode/password:password-interface(make-instance'password:keepassxc-interface)))) (define-configurationbuffer ((default-modes(append(list'nyxt/mode/password:password-mode)%slot-value%))))
Appearance
#
Appearance
#
Much of the visual style can be configured by the user. You can use the
facilities provided by
theme
and
browser theme slot
. The simplest option would be to use a built-in theme:
(define-configurationbrowser ((themetheme:+dark-theme+:doc "Setting dark theme. The default istheme:+light-theme+.")))
There's also an option of creating a custom theme. For example, to set a theme to a midnight-like one, you can add this snippet to your configuration file:
(define-configurationbrowser ((theme(make-instance'theme:theme:background-color "black" :action-color "#37a8e4" :primary-color "#808080" :secondary-color "darkgray") :doc "You can omit the colors you like in default theme, and they will stay as they were.")))
This, on the next restart of Nyxt, will repaint all the interface elements into a dark-ish theme.
As a more involved theme example, here's how one can redefine most of the semantic colors Nyxt uses to be compliant with Solarized Light theme:
(define-configurationbrowser ((theme(make-instance'theme:theme:background-color "#eee8d5" :action-color "#268bd2" :primary-color "#073642" :secondary-color "#586e75" :success-color "#2aa198" :warning-color "#dc322f" :highlight-color "#d33682") :doc "Covers all the semantic groups (warning-color,codeblock-coloretc.) Note that you can also define more nuanced colors, likewarning-color+, so that the interface gets even nicer. Otherwise Nyxt generates the missing colors automatically, which should be good enough... for most cases.")))
As an alternative to the all-encompassing themes, you can alter the style of
every individual class controlling Nyxt interface elements. All such classes
have a
style
slot that you can configure with your own CSS like this:
(define-configurationnyxt/mode/style:dark-mode ((style(theme:themed-css(theme *browser*) `(*:background-color ,theme:background-color "!important" :background-image none "!important" :color "red" "!important") `(a :background-color ,theme:background-color "!important" :background-image none "!important" :color "#AAAAAA" "!important")))) :doc "Notice the use oftheme:themed-cssfor convenient theme color injection.")
This snippet alters the
style
of Nyxt dark mode to have a more theme-compliant colors, using the
theme:themed-css
macro (making all the theme colors you've configured earlier available as
variables like
theme:on-primary-color
.)
Status buffer appearance
#
Status buffer appearance
#
You can customize the layout and styling of
status-buffer
using the methods it uses for layout. These methods are:
-
format-status - General layout of the status buffer, including the parts it consists of.
-
format-status-buttons - The ("Back", "Forward", "Reload") buttons section.
-
format-status-url - The current URL display section.
-
format-status-tabs - Tab listing.
-
format-status-new-buffer - The button that opens a new buffer.
-
format-status-modes - List of modes.
To complement the layout produced by these
format-*
functions, you might need to add more rules or replace the
style of status buffer
.
Scripting
#
Scripting
#
You can evaluate code from the command line with
--eval
and
--load
. From a shell:
$ nyxt --no-config --eval '+version+' --load my-lib.lisp --eval '(format t "Hello ~a!~&" (my-lib:my-world))'
You can evaluate multiple --eval and --load in a row, they are executed in the order they appear.
You can also evaluate a Lisp file from the Nyxt interface with the
load-file
(
unbound
)
command. For convenience,
load-config-file
(
unbound
)
(re)loads your initialization file.
You can even make scripts. Here is an example foo.lisp:
#!/bin/sh #| exec nyxt --script "$0" |# ;; Your code follows: (format t "~a~&" +version+)
--eval and --load can be commanded to operate over an existing instance instead of a separate instance that exits immediately.
The
remote-execution-p
of the remote instance must be non-nil:
(define-configurationbrowser ((remote-execution-pt)))
To let know a private instance of Nyxt to load a foo.lisp script and run its
foo
function:
nyxt --profile nosave --remote --load foo.lisp --eval '(foo)' --quit
Note that
--quit
at the end of each Nyxt CLI call here. If you don't provide
--quit
when dealing with a remote instance, it will go into a REPL mode, allowing an
immediate communication with an instance:
nyxt --remote
(echo "~s" (+ 1 2)) ;; Shows '3' in the message buffer of remote Nyxt
Advanced configuration
#
Advanced configuration
#
While
define-configuration
is convenient, it is mostly restricted to class slot configuration. If you want
to do anything else on class instantiation, you'll have to specialize the
lower-level
customize-instance
generic function. Example:
All classes with metaclass
user-class
call
customize-instance
on instantiation, after
initialize-instance
:after
. The primary method is reserved to the user, however the
:after
method is reserved to the Nyxt core to finalize the instance.
Extensions
#
Extensions
#
To install an extension, copy inside the
*extensions-directory*
(default to
~/.local/share/nyxt/extensions
).
Extensions are regular Common Lisp systems.
Blocking ads using AdBlock rules
#
Blocking ads using AdBlock rules
#With WebkitGTK backend you can use BlocKit extension to block ads.
In short, you have to install
adblock-rust-server
to a directory visible in
PATH
environment variable and the shared library (
blockit.so
) to
/usr/local/lib/nyxt/
. After that, follow instructions on BlocKit github page.
Troubleshooting
#
Troubleshooting
#
Debugging and reporting errors
#
Debugging and reporting errors
#
Report bugs using
report-bug
(
unbound
)
.
Bwrap error on initialization (Ubuntu)
#
Bwrap error on initialization (Ubuntu)
#
If Nyxt crashes on start due to
bwrap
, then disable or configure the
apparmor
service.
Playing videos
#
Playing videos
#Nyxt delegates video support to third-party plugins.
When using the WebKitGTK backends, GStreamer and its plugins are leveraged. Depending on the video, you will need to install some of the following packages:
- gst-libav
- gst-plugins-bad
- gst-plugins-base
- gst-plugins-good
- gst-plugins-ugly
On Debian-based systems, you might be looking for (adapt the version numbers):
- libgstreamer1.0-0
- gir1.2-gst-plugins-base-1.0
For systems from the Fedora family:
- gstreamer1-devel
- gstreamer1-plugins-base-devel
After the desired plugins have been installed, clear the GStreamer cache at
~/.cache/gstreamer-1.0
and restart Nyxt.
Website crashes
#
Website crashes
#If some websites systematically crash, try to install all the required GStreamer plugins as mentioned in the 'Playing videos' section.
Input method support (CJK, etc.)
#
Input method support (CJK, etc.)
#Depending on your setup, you might have to set some environment variables or run some commands before starting Nyxt, for instance
GTK_IM_MODULE=xim XMODIFIERS=@im=ibus ibus --daemonize --replace --xim
You can persist this change by saving the commands in your
.xprofile
or similar.
HiDPI displays
#
HiDPI displays
#The entire UI may need to be scaled up on HiDPI displays.
When using the WebKitGTK renderer, export the environment variable below before
starting Nyxt. Note that
GDK_DPI_SCALE
(not to be confused with
GDK_SCALE
) scales text only, so tweaking it may be undesirable.
export GDK_SCALE=2
nyxt
StumpWM mouse scroll
#
StumpWM mouse scroll
#If the mouse scroll does not work for you, see the StumpWM FAQ for a fix.
Blank WebKitGTK views
#
Blank WebKitGTK views
#When experiencing rendering issues, try to disable compositing as below:
(setf (uiop/os:getenv "WEBKIT_DISABLE_COMPOSITING_MODE") "1")
Missing cursor icons
#
Missing cursor icons
#
If you are having issues with the cursor not changing when hovering over buttons
or links, it might be because Nyxt can't locate your cursor theme. To fix
that, try adding the following to your
.bash_profile
or similar:
export XCURSOR_PATH=${XCURSOR_PATH}:/usr/share/icons
export XCURSOR_PATH=${XCURSOR_PATH}:~/.local/share/icons
