@@ -45,8 +45,8 @@ similar programming language.")
4545 (:p " Example:"
4646 (:ncode
4747 ' (define-configuration web-buffer
48- ((default-modes (pushnew ' nyxt/mode/no-script :no-script -mode %slot-value%)))))
49- (:p " The above turns on the 'no-script -mode' (disables JavaScript ) by default for
48+ ((default-modes (pushnew ' nyxt/mode/no-sound :no-sound -mode %slot-value%)))))
49+ (:p " The above turns on the 'no-sound -mode' (disables sound ) by default for
5050every buffer." )
5151 (:p " The " :nxref :macro ' define-configuration) " macro can be used to customize
5252the slots of classes like the browser, buffers, windows, etc." )
@@ -190,16 +190,6 @@ commands like " (:nxref :command 'nyxt/mode/history:history-backwards) " and "
190190 (:p " See the " :nxref :command ' nyxt/mode/download:list-downloads) " command and the "
191191 (:nxref :slot ' download-path :class-name ' buffer) " buffer slot documentation."
192192
193- (:nsection :title " Proxy and Tor"
194- (:p " See the " :nxref :class-name ' nyxt/mode/proxy:proxy-mode) " documentation."
195-
196- (:nsection :title " Blocker mode"
197- (:p " This mode blocks access to websites related to specific hosts. To see
198- all hosts being blocked, execute command " (:code " describe-variable" " , choose variable "
199- (:code " NYXT/MODE/BLOCKER:*DEFAULT-HOSTLIST*" " , and read data on "
200- (:code " nyxt/mode/blocker:url-body" " slot." " To customize host blocking, read the "
201- (:nxref :class-name ' nyxt/mode/blocker:blocker-mode) " documentation."
202-
203193 (:nsection :title " URL-dispatchers"
204194 (:p " You can configure which actions to take depending on the URL to be
205195loaded. For instance, you can configure which Torrent program to start to load
@@ -571,159 +561,6 @@ immediate communication with an instance:")
571561 (:pre (:code " nyxt --remote
572562(echo \" ~s \" (+ 1 2)) ;; Shows '3' in the message buffer of remote Nyxt" )))
573563
574- (:nsection :title " User scripts"
575- (:p " User scripts are a conventional and lightweight way to run arbitrary JavaScript
576- code on some set of pages/conditions. While not as powerful as either
577- WebExtensions on Lisp-native extensions to Nyxt, those hook into the tenderer
578- inner working and allow you to change the page and JavaScript objects associated
579- to it." )
580- (:p " As an example, you can remove navbars from all the pages you visit with this
581- small configuration snippet (note that you'd need to have "
582- (:nxref :class-name ' nyxt/mode/user-script:user-script-mode)
583- " in your " :nxref :function ' default-modes " buffer default-modes" " ):"
584- (:ncode
585- ' (define-configuration web-buffer
586- " Enable user-script-mode, if you didn't already."
587- ((default-modes (pushnew ' nyxt/mode/user-script:user-script-mode %slot-value%))))
588-
589- ' (define-configuration nyxt/mode/user-script :user-script-mode
590- ((nyxt/mode/user-script :user-scripts
591- (list
592- (make-instance ' nyxt/mode/user-script:user-script
593- :code " // ==UserScript==
594- // @name No navbars!
595- // @description A simple script to remove navbars
596- // @run-at document-end
597- // @include http://*/*
598- // @include https://*/*
599- // @noframes
600- // ==/UserScript==
601-
602- var elem = document.querySelector(\" header\" ) || document.querySelector(\" nav\" );
603- if (elem) {
604- elem.parentNode.removeChild(elem);
605- }" ))
606- :doc " Alternatively, save the code to some file and use
607- :base-path #p\" /path/to/our/file.user.js\" .
608- Or fetch a remote script with
609- url (quri:uri \" https://example.com/script.user.js\" )" ))))
610- (:p (:a :href " https://wiki.greasespot.net/Metadata_Block" " Greasemonkey documentation"
611- " lists all the possible properties that a user script might have. To Nyxt
612- implementation, only those are meaningful:" )
613- (:dl
614- (:dt " @include and " :nxref :function ' nyxt/mode/user-script:include))
615- (:dd " Sets the URL pattern to enable this script for. Follows the pattern "
616- (:code " scheme://host/path"
617- " , where scheme is either a literal scheme or and asterisk (matching any
618- scheme), and host and path are any valid characters plus asterisks (matching any
619- set of characters) anywhere." )
620- (:dt " @match"
621- (:dd " Same as @include."
622- (:dt " @exclude and " :nxref :function ' nyxt/mode/user-script:exclude))
623- (:dd " Similar to @include, but rather disables the script for the matching pages."
624- (:dt " @noframes and " :nxref :function ' nyxt/mode/user-script:all-frames-p))
625- (:dd " When present, disables the script for all the frames but toplevel ones. When
626- absent, injects the script everywhere. The Lisp-side"
627- (:nxref :function ' nyxt/mode/user-script:all-frames-p) " works in an opposite way."
628- (:dt " @run-at and " :nxref :function ' nyxt/mode/user-script:run-at))
629- (:dd " When to run a script. Allowed values: document-start, document-end,
630- document-idle (in Nyxt implementation, same as document-end)." )
631- (:dt " @require"
632- (:dd " Allows including arbitrary JS files hosted on the Internet or loaded from the
633- same place as the script itself. Neat for including some JS libraries, like jQuery." )))
634-
635- (:nsection :title " Headless mode"
636- (:p " Similarly to Nyxt's scripting functionality, headless mode runs without a
637- graphical user interface. Possible use-cases for this mode are web scraping,
638- automations and web page analysis." )
639- (:p " To enable headless mode, simply start Nyxt with the "
640- (:code " --headless"
641- " CLI flag and provide a script file to serve as the configuration file:"
642- (:ncode
643- " nyxt --headless --config /path/to/your/headless-config.lisp"
644- (:p " Note that you pass it a " :i " configuration file" " ,
645- i.e. headless mode is only different from the regular Nyxt functions
646- in that it has no GUI, and is all the same otherwise, contrary to
647- all the seeming similarities to the " (:code " --script" " flag
648- usage." )
649- (:p " The example below showcases frequent idioms that are found in the
650- mode's configuration file:" )
651- (:ncode
652- " #!/bin/sh
653- #|
654- exec nyxt --headless --no-auto-config --profile nosave --config \" $0\"
655- |#"
656- ' (define-configuration browser
657- " Load the URL of Nyxt repository by default in all new buffers.
658- Alternatively, call `buffer-load' in `after-startup-hook'."
659- ((default-new-buffer-url (quri :uri " https://github.com/atlas-engineer/nyxt"
660- " \( hooks:on (after-startup-hook *browser*) (browser)
661- ;; Once the page's done loading, do your thing.
662- (hooks:once-on (buffer-loaded-hook (current-buffer)) (buffer)
663- ;; It's sometimes necessary to sleep, as `buffer-loaded-hook' fires when the
664- ;; page is loaded, which does not mean that all the resources and scripts
665- ;; are done loading yet. Give it some time there.
666- (sleep 0.5)
667- ;; All the Nyxt reporting happens in headless mode, so you may want to log
668- ;; it with `echo' and `echo-warning'.
669- (echo \" Nyxt GitHub repo open.\" )
670- ;; Updating the `document-model' so that it includes the most relevant
671- ;; information about the page.
672- (nyxt:update-document-model)
673- ;; Click the star button.
674- (nyxt/dom:click-element
675- (elt (clss:select \" [aria-label=\\\" Star this repository\\\" ]\"
676- (document-model buffer))
677- 0))
678- (echo \" Clicked the star.\" )
679- ;; It's good tone to `nyxt:quit' after you're done, but if you use nyxt
680- ;; --no-socket, you don't have to. Just be ready for some RAM eating :)
681- (nyxt:quit)))" )
682- (:p " The contents of headless-config.lisp feature configuration forms that
683- make Nyxt perform some actions to the opened pages and/or on certain
684- hooks. Things you'd most probably want to put there are: " )
685- (:ul
686- (:li " Hook bindings, using the " :nxref :package ' nhooks)
687- " library and hooks provided by Nyxt."
688- (:li " Operations on the page. Check the " :nxref :package ' nyxt/dom) "
689- library and the " (:nxref :function ' document-model) " method."
690- (:ul
691- (:li " The " :nxref :function ' document-model)
692- " method has a reasonably fresh copy of the page DOM (Document Object Model,
693- reflecting the dynamic structure of the page). It is a " (:nxref :package ' plump " Plump"
694- " DOM, which means that all " :nxref :package ' plump " Plump" " (and "
695- (:nxref :package ' clss " CLSS" " ) functions can be used on it."
696- (:li (:nxref :function ' update-document-model)
697- " is a function to force DOM re-parsing for the cases when you consider the
698- current " (:nxref :function ' document-model) " too outdated."
699- (:li (:nxref :function ' clss:select)
700- " is a CLSS function to find elements using CSS selectors (a terse
701- notation for web page element description)." )
702- ; ; FIXME: Make a nxref once we update CLSS submodule.
703- (:li (:code" clss:ordered-select" " is the same as "
704- (:nxref :function ' clss:select)
705- " , except it guarantees that all the elements are returned in a
706- depth-first traversal order." )
707- (:li (:nxref :function ' nyxt/dom:click-element)
708- " to programmatically click a certain element (including the ones returned by "
709- (:nxref :function ' clss:select) " .)"
710- (:li (:nxref :function ' nyxt/dom:focus-select-element) " to focus an input
711- field, for example." )
712- (:li (:nxref :function ' nyxt/dom:check-element) " to check a checkbox or a radio button."
713- (:li (:nxref :function ' nyxt/dom:select-option-element) " to select an option from the "
714- (:code " <select>" " element options."
715- (:p " Additionally, headless mode gracefully interacts with other CLI toggles the
716- Nyxt has:" )
717- (:ul
718- (:li (:code " --headless" " itself! Notice that you can debug your script
719- by omitting this CLI flag. When you're confident enough about it, put it back
720- in. A good debugging tip, isn't it?" )
721- (:li (:code " --no-socket"
722- " flag allows starting as many Nyxt instances as your machine can
723- handle. Useful to parallelize computations." )
724- (:li (:code " --profile nosave"
725- " to not pollute your history and cache with the script-accessed pages."
726-
727564 (:nsection :title " Advanced configuration"
728565 (:p " While " :nxref :macro ' define-configuration) " is convenient, it is mostly
729566restricted to class slot configuration. If you want to do anything else on
0 commit comments