2 This is part of the VimFx documentation.
3 Copyright Simon Lydell 2015, 2016.
4 See the file README.md for copying conditions.
9 VimFx has many options that can be configured, but they all have nice defaults
10 so you shouldn’t need to.
12 Advanced users might also be interested in [styling] VimFx and writing a [config
16 [config file]: config-file.md
21 These options are available in VimFx’s settings page in the Add-ons Manager
22 (where you can also customize [keyboard shortcuts]).
24 [keyboard shortcuts]: shortcuts.md
28 The characters used for the hints in Hints mode, which can be entered using one
29 of the many `f` commands. See also [The `f` commands].
31 [The `f` commands]: commands.md#the-f-commands--hints-mode
33 ### “Previous”/“Next” link patterns
35 Space separated lists of patterns that match links to the previous/next page.
36 Used by the `[` and `]` commands.
38 There is a standardized way for websites to tell browsers the URLs to the
39 previous and next page. VimFx looks for that information in the first place.
40 Unfortunately, many websites don’t provide this information. Then VimFx falls
41 back on looking for links on the page that seem to go to the previous/next page
44 The patterns are matched at the beginning and end of link text (and the
45 attributes defined by the advanced setting [`pattern_attrs`]). The patterns do
46 not match in the middle of words, so “previous” does not match “previously”.
47 The matching is case <strong>in</strong>sensitive.
49 Actually, the patterns are regular expressions. If you do not know what a
50 regular expression is, that’s fine. You can type simple patterns like the
51 default ones without problems. If you do know what it is, though, you have the
52 possibility to create more advanced patterns if needed.
54 Some of the default patterns are English words. You might want to add
55 alternatives in your own language.
57 Note: If you need to include a space in your pattern, use `\s`. For example:
60 [`pattern_attrs`]: #pattern_attrs
64 Space separated list of URLs where VimFx should automatically enter Ignore mode.
67 *example.com* http://example.org/editor/*
69 Note that the URLs in the list must match the current URL _entirely_ for it to
70 apply. Therefore it is easiest to always use the `*` wildcard (which matches
71 zero or more characters).
73 Set the option to `*` to make VimFx start out in Ignore mode _everywhere._
75 When you’re done editing the blacklist, go to one of the pages you intend to
76 match. If you already have a tab open for that page, reload it. Then look at
77 VimFx’s [button] to see if your edits work out.
79 Note that when Ignore mode is automatically entered because of the blacklist, it
80 is also automatically exited (returning to Normal mode) if you go to a
81 non-blacklisted page in the same tab. On the other hand, if you entered Ignore
82 mode by pressing `i`, you’ll stay in Ignore mode in that tab until you exit it,
83 even if you navigate to another page.
85 You might also want to read about the [Ignore mode `<s-f1>` command][s-f1].
88 [s-f1]: commands.md#ignore-mode-s-f1
90 #### Blacklisting specific elements
92 VimFx automatically enters Ignore mode while Vim-style editors are focused, such
93 as the [wasavi] extension and [CodeMirror editors in Vim mode][codemirror-vim].
95 By default, VimFx lets you press `<escape>` to blur text inputs. Also by
96 default, Vim-style editors use `<escape>` to exit from their Insert mode to
97 their Normal mode. In other words, there is a keyboard shortcut conflict here.
99 It makes the most sense to let the Vim-style editor “win.” That’s why VimFx
100 (temporarily) enters Ignore mode when focusing such an editor. In Insert mode,
101 there is no `<escape>` shortcut (by default), and thus no conflict. Instead,
102 there’s `<s-escape>` to blur the current element and exit Ignore mode.
103 `<s-escape>` was chosen because it is very unlikely to cause conflicts. If it
104 ever does, there’s the [`<s-f1>`] command to the rescue.
106 There is currently no way of specifying your own elements to be blacklisted, but
107 such a feature could be added if there’s demand for it.
109 [wasavi]: http://appsweets.net/wasavi/
110 [codemirror-vim]: https://codemirror.net/demo/vim.html
111 [`<s-f1>`]: commands.md#ignore-mode-s-f1
113 ### Prevent autofocus
115 Many sites autofocus their search box, for example. This might be annoying when
116 browsing using the keyboard, as you do with VimFx, because it often feels like
117 VimFx isn’t responding, until you realize that you are typing in a text box—not
118 running VimFx commands!
120 For this reason VimFx can prevent autofocus. It’s not enabled by default,
121 though, since one of VimFx’s key features is to be nice to your browser and your
124 If enabled, all focusing that occurs on page load, or after you’ve just switched
125 back to a tab from another, until you interact with the page is prevented.
127 #### Technical notes and trivia
129 Autofocus on page load and when coming back to a tab are the two most common
130 cases. Some sites, though, automatically focus a text input in other cases as
131 well. Trying to catch those cases as well, VimFx used to prevent all focusing
132 that didn’t occur within a fixed number of milliseconds after your last
133 interaction (click or keypress). However, this proved to be too aggressive,
134 preventing too much focusing. In other words, the time-based check was not
135 sufficient to distinguish between intended focusing and automatic unwanted
136 focusing. It made things worse more than it helped. Since these cases are so
137 difficult (if not impossible) to detect, it is better to leave them. Thankfully
138 they are not very common.
140 On page load or when coming back to a tab, before you have interacted with the
141 page in any way, we can be _sure_ that any focusing is automatic (not caused by
142 you), which makes it safe to prevent all focusing in those time spans.
144 ### Ignore keyboard layout
146 If you use more than one keyboard layout, you probably want to enable this
149 People who use a keyboard layout _without_ the letters A–Z usually also use the
150 standard en-US QWERTY layout as well.
152 This option makes VimFx ignore your current layout and pretend that the standard
153 en-US QWERTY layout is _always_ used. This way the default shortcuts work even
154 if your layout doesn’t contain the letters A–Z and all shortcuts can be typed by
155 the same physical keys on your keyboard regardless of your current keyboard
158 (If you’d like VimFx to pretend that some other keyboard layout than the
159 standard en-US QWERTY is always used, you may do so with the special option
162 [`translations`]: #translations
166 The maximum amount of time (in milliseconds) that may pass between two
167 keypresses of a shortcut.
169 It’s easy to press, say, `a` by mistake while browsing. Without a timeout, you
170 might be surprised that all search results are highlighted when you a bit later
171 try to search using the `/` command. (That’s what `a/` does.) _With_ a timeout,
172 the `a` would be cancelled when the timeout has passed.
177 These options are _not_ available in VimFx’s settings page in the Add-ons
178 Manager. They can only be changed in [about:config] or using a [config file].
179 They all start with `extensions.VimFx.`.
181 (There are actually a few more advanced options than those listed here. You can
182 see them all in [defaults.coffee].)
184 [about:config]: http://kb.mozillazine.org/About:config
185 [config file]: config-file.md
186 [defaults.coffee]: ../extension/lib/defaults.coffee
188 ### `notifications_enabled`
190 Controls whether [notifications] should be shown or not.
192 You can also choose to show notifications any way you want by listening for the
193 [the `notification` and `hideNotification` events][notification-events].
195 [notifications]: notifications.md
196 [notification-events]: api.md#the-notification-and-hidenotification-events
198 ### `notify_entered_keys`
200 If enabled, a [notification] is shown with the keys you have entered so far of
201 a command. This is only noticeable if you type a multi-key shortcut or use a
204 [notification]: notifications.md
206 ### `prevent_target_blank`
208 You might have noticed that some links open in new tabs when you click them.
209 That is not the case if you “click” them using VimFx’s `f` command, though. If
210 you dislike that, disable this option.
214 Controls whether [counts] are enabled or not.
216 [counts]: commands.md#counts
218 ### `find_from_top_of_viewport`
220 Toggles whether the various find commands are Vim-style or Firefox
223 Disable this pref if you want `/` to work more like `<c-f>` and `n`/`N` to work
224 more like `<f3>`/`<s-f3>`.
226 If there is selected text on the page, Firefox starts searching after that.
227 VimFx does so too, but only if the selection is currently _visible_ (inside the
230 If there _isn’t_ selected text on the page, Firefox starts searching from the
231 top of the page. VimFx instead starts searching from the top of the current
234 The VimFx behavior is designed to be less disorienting. It is also similar to
235 how searching in Vim works. Again, you can return to the Firefox default
236 behavior (if you prefer that) by disabling this pref.
238 One of the main benefits of the VimFx behavior is that you can scroll past a
239 block of the text with lots of search matches and then continue going through
240 matches with `n` after that block, without having to spam `n` lots and lots of
243 ### `ignore_ctrl_alt`
245 This option is enabled by default on Windows, and disabled otherwise.
247 If enabled, ignores ctrl+alt for printable keys. `<a-c-$>` becomes `$` and
248 `<a-c-A>` becomes `A`, while `<a-c-enter>` stays the same.
250 This option is suitable on Windows, which treats [AltGr as
251 ctrl+alt][wikipedia-altgr]. For example, if a user of the sv-SE layout on
252 Windows holds AltGr and presses the key labeled `4`, in order to produce a `$`,
253 the result would be `<a-c-$>` without this option, making it impossible to
254 trigger a keyboard shortcut containing `$`. _With_ this option the result is
255 `$`, as expected (and as on GNU/Linux). On the other hand it won’t be possible
256 to trigger keyboard shortcuts such as `<a-c-a>`, but ctrl+alt keyboard shortcuts
257 are [discouraged on Windows][wikipedia-altgr] anyway because of this reason.
259 [wikipedia-altgr]: https://en.wikipedia.org/wiki/AltGr_key#Control_.2B_Alt_as_a_substitute
261 ### `prevent_autofocus_modes`
263 Space separated list of modes where `prevent_autofocus` should be used.
265 ### `config_file_directory`
267 VimFx can optionally be customized using a [config file]. If you want to that,
268 you need to tell VimFx where that file is. That’s what this pref is for.
270 By default this pref is blank (the empty string), which means that no config
271 file should be loaded.
273 If non-blank, it should be the path to the directory where the config file
274 exists. See the [config file] documentation for more information.
276 [config file]: config-file.md
280 The number of milliseconds a matched hint marker should stay on screen before
281 disappearing (or resetting).
285 In Hints mode, VimFx continually checks if the element for a hint marker has
286 moved. If so, the marker is moved as well. This pref controls how many
287 milliseconds VimFx should “sleep” between each check. The shorter, the more CPU
288 usage, the longer, the more stuttery marker movement.
290 The default value should work fine, but if you have a low-performing computer
291 and you notice bothering CPU usage during Hints mode you might want to raise the
294 Set it to -1 to disable the marker movement feature entirely.
298 Apart from its own prefs, VimFx also respects a few built-in Firefox prefs.
300 #### Smooth scrolling
302 If you want to customize Firefox’s smooth scrolling, adjusting
303 `general.smoothScroll.{lines,pages,other}.duration{Min,Max}MS` is the way to
304 go. VimFx has similar prefs for the scrolling commands, but they work like
305 `layout.css.scroll-behavior.spring-constant`.
307 Basically, the higher the value, the faster the scrolling.
309 These are VimFx’s variants, and the commands they affect:
311 - `smoothScroll.lines.spring-constant`: `h`, `l`, `j`, `k`
312 - `smoothScroll.pages.spring-constant`: `d`, `u`, `<space>`, `<s-space>`
313 - `smoothScroll.other.spring-constant`: `gg`, `G`, `0`, `^`, `$`, `` ` ``
315 Note that the value of these prefs are _strings,_ not numbers!
317 Unfortunately, Firefox provides no way for code to tell which “spring constant”
318 it wants when scrolling smoothly. All VimFx can do is to temporarily set
319 Firefox’s `layout.css.scroll-behavior.spring-constant` pref. It is reset again
320 after one second (by default). If that doesn’t work out for you, you can
321 customize that timeout using the `scroll.reset_timeout` pref.
323 The Firefox pref `general.smoothScroll` lets you turn off smooth scrolling
324 entirely, including all of VimFx’s scrolling commands.
326 `general.smoothScroll.lines`, `general.smoothScroll.pages`, and
327 `general.smoothScroll.other` lets you selectively disable smooth scrolling.
328 VimFx’s scrolling commands follow the same “lines,” “pages” and “other”
329 categorization as in the above list.
333 By default you can scroll using the arrow keys in Firefox. You can control how
334 much they scroll by adjusting the following prefs:
336 - `toolkit.scrollbox.horizontalScrollDistance`: `<left>`, `<right>`, `h`, `l`
337 - `toolkit.scrollbox.verticalScrollDistance`: `<down>`, `<up>`, `j`, `k`
339 (VimFx used to have a `scroll_step` pref, but is has been replaced by the
342 #### `scroll.full_page_adjustment` and `scroll.half_page_adjustment`
344 An important use case for scrolling a full page down is to read an entire page
345 (a window-full) of text, press `<space>` and then continue reading the next
346 page. However, if you can only see, say, _half_ of the height the last line,
347 pressing `<space>` would give you the other half, but reading only the top or
348 bottom parts of letters is difficult. Even if the lines happen to line up with
349 the window edge to not be sliced horizontally, it might feel disorienting
352 For this reason, both VimFx and Firefox by default scroll _about a line less
353 than a whole page_ when pressing `<space>`. This solves the sliced-last-line
354 problem, and provides some context on where you are in the text you’re reading.
356 These two prefs control how many pixels “about a line” actually means for the
357 different page scrolling commands.
359 - `scroll.full_page_adjustment`: `<space>, `<s-space>`
360 - `scroll.half_page_adjustment`: `d`, `u`
362 #### `scroll.last_position_mark`
364 The special mark for the [`` ` ``][scroll-to-mark] command that takes you to the
367 [scroll-to-mark]: commands.md#marks-m-and-
369 ### `pattern_selector`
371 A CSS selector that targets candidates for a previous/next page link.
375 A space-separated list of attributes that the [“Previous”/“Next” link patterns]
376 should be matched against.
378 [“Previous”/“Next” link patterns]: #previousnext-link-patterns
380 ### `hints_toggle_in_tab`
382 If the keypress that matched a hint starts with this string, toggle whether to
383 open the matched link in the current tab or a new tab. See [The `f` commands]
384 for more information.
386 ### `hints_toggle_in_background`
388 If the keypress that matched a hint starts with this string, open the matched
389 link in a new tab and toggle whether to open that tab in the background or
390 foreground. See [The `f` commands] for more information.
392 ### `activatable_element_keys`
394 Keys that should not trigger VimFx commands but be sent through to the page if
395 an “activatable” element (link or button) is focused.
397 ### `adjustable_element_keys`
399 Keys that should not trigger VimFx commands but be sent through to the page if
400 an “adjustable” element (form control or video player) is focused.
402 ### `focus_previous_key` and `focus_next_key`
404 The default values are `<s-tab` and `<tab>`, respectively. Those keys are
405 specially handled after focusing a text input using [`gi`]. To disable this
406 special handling, set the prefs to the empty string.
408 [`gi`]: commands.md#gi-1
413 These options are available in neither VimFx’s settings page in the Add-ons
414 Manager nor in [about:config]. The only way to change them is by using the
419 See the description of the `translations` option in [vim-like-key-notation].
421 [vim-like-key-notation]: https://github.com/lydell/vim-like-key-notation#api
425 See the documentation for [`vimfx.get('categories')`][categories].
427 [categories]: api.md#vimfxgetcategories