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 Many sites autofocus their search box, for example. This might be annoying when
29 browsing using the keyboard, as you do with VimFx, because it often feels like
30 VimFx isn’t responding, until you realize that you are typing in a text box—not
31 running VimFx commands!
33 For this reason VimFx can prevent autofocus. It’s not enabled by default,
34 though, since one of VimFx’s key features is to be nice to your browser and your
37 If enabled, all focusing that occurs on page load, or after you’ve just switched
38 back to a tab from another, until you interact with the page is prevented.
40 #### Technical notes and trivia
42 Autofocus on page load and when coming back to a tab are the two most common
43 cases. Some sites, though, automatically focus a text input in other cases as
44 well. Trying to catch those cases as well, VimFx used to prevent all focusing
45 that didn’t occur within a fixed number of milliseconds after your last
46 interaction (click or keypress). However, this proved to be too aggressive,
47 preventing too much focusing. In other words, the time-based check was not
48 sufficient to distinguish between intended focusing and automatic unwanted
49 focusing. It made things worse more than it helped. Since these cases are so
50 difficult (if not impossible) to detect, it is better to leave them. Thankfully
51 they are not very common.
53 On page load or when coming back to a tab, before you have interacted with the
54 page in any way, we can be _sure_ that any focusing is automatic (not caused by
55 you), which makes it safe to prevent all focusing in those time spans.
57 ### Ignore keyboard layout
59 If you use more than one keyboard layout, you probably want to enable this
62 People who use a keyboard layout _without_ the letters A–Z usually also use the
63 standard en-US QWERTY layout as well.
65 This option makes VimFx ignore your current layout and pretend that the standard
66 en-US QWERTY layout is _always_ used. This way the default shortcuts work even
67 if your layout doesn’t contain the letters A–Z and all shortcuts can be typed by
68 the same physical keys on your keyboard regardless of your current keyboard
71 Note that when filtering hints markers by element text (but not when typing hint
72 characters) in [Hints mode], your current layout _is_ used, even if you’ve
73 enabled ignoring of it. That’s because otherwise you wouldn’t be able to filter
74 by element text in any other language than English.
76 (If you’d like VimFx to pretend that some other keyboard layout than the
77 standard en-US QWERTY is always used, you may do so with the special option
80 [Hints mode]: commands.md#the-hint-commands--hints-mode
81 [`translations`]: #translations
85 Space separated list of URL patterns where VimFx should automatically enter
88 *example.com* http://example.org/editor/*
90 The fastest way to blacklist the page you’re currently on, is to use the `gB`
91 command. It opens a modal with a text input filled in with the blacklist, and
92 with `*currentdomain.com*` added at the start for you! Edit it if needed, or
93 just press `<enter>` straight away to save. Ignore mode is then automatically
94 entered (if the URL patterns apply).
96 Note that the URLs in the list must match the current URL _entirely_ for it to
97 apply. Therefore it is easiest to always use the `*` wildcard (which matches
98 zero or more characters).
100 Set the option to `*` to make VimFx start out in Ignore mode _everywhere._
102 When you’re done editing the blacklist, go to one of the pages you intend to
103 match. If you already have a tab open for that page, reload it. Then look at
104 VimFx’s [button] to see if your edits work out.
106 Note that when Ignore mode is automatically entered because of the blacklist, it
107 is also automatically exited (returning to Normal mode) if you go to a
108 non-blacklisted page in the same tab. On the other hand, if you entered Ignore
109 mode by pressing `i`, you’ll stay in Ignore mode in that tab until you exit it,
110 even if you navigate to another page.
112 You might also want to read about the [Ignore mode `<s-f1>` command][s-f1].
115 [s-f1]: commands.md#ignore-mode-s-f1
117 #### Blacklisting specific elements
119 VimFx automatically enters Ignore mode while Vim-style editors are focused, such
120 as the [wasavi] extension and [CodeMirror editors in Vim mode][codemirror-vim].
122 By default, VimFx lets you press `<escape>` to blur text inputs. Also by
123 default, Vim-style editors use `<escape>` to exit from their Insert mode to
124 their Normal mode. In other words, there is a keyboard shortcut conflict here.
126 It makes the most sense to let the Vim-style editor “win.” That’s why VimFx
127 (temporarily) enters Ignore mode when focusing such an editor. In Ignore mode,
128 there is no `<escape>` shortcut (by default), and thus no conflict. Instead,
129 there’s `<s-escape>` to blur the current element and exit Ignore mode.
130 `<s-escape>` was chosen because it is very unlikely to cause conflicts. If it
131 ever does, there’s the [`<s-f1>`] command to the rescue.
133 There is currently no way of specifying your own elements to be blacklisted, but
134 such a feature could be added if there’s demand for it.
136 [wasavi]: http://appsweets.net/wasavi/
137 [codemirror-vim]: https://codemirror.net/demo/vim.html
138 [`<s-f1>`]: commands.md#ignore-mode-s-f1
142 The characters used for the hints in Hints mode, which can be entered using one
143 of the many [hint commands].
145 Tip: Prefer filtering hints by element text? Use only uppercase hint characters,
148 #### Easy-to-type and performant hints
150 Quick suggestion: Put more easily reachable keys longer to the left. Put two
151 pretty good (but not the best) keys at the end, after the space.
153 Some hint characters are easier to type than others. Many people think that the
154 ones on the home row are the best. VimFx favors keys to the left. That’s why you
155 should put better keys longer to the left.
157 The hint characters always contain a single space. This splits them into two
158 groups: _primary_ hint characters (before the space), and _secondary_ hint
159 characters (after the space). Read on to find out why.
161 Some markable elements are quicker to find than others. Therefore, VimFx looks
162 for markable elements in two passes for some commands, such as the `f` command.
163 (This is why all hints don’t always appear on screen at the same time). If two
164 passes are used, hints from the _first_ pass can only begin with _primary_ hint
165 characters. In all other cases hints may start with _any_ hint character.
167 When choosing how many secondary hint characters you want (there are two by
168 default), think about this: Usually most markable elements are found in the
169 first pass, while fewer are found in the second pass. So it makes sense to have
170 more primary hint characters than secondary. It’s a tradeoff. If you think the
171 hints from the first pass are too long, you probably need more primary hint
172 characters. On the other hand, if you think the hints from the _second_ pass are
173 too long, you might need a few extra secondary hint characters, but remember
174 that it might be at the expense of longer hints in the first pass.
176 All of this also help you understand why hints may be slow on some pages:
178 - One reason could be that most hints come from a second pass, which are slower
179 to compute (and are worse than first pass hints).
181 If a site gets an unusual amount of second pass hints, it might be because the
182 site is badly coded accessibility-wise. If so, consider contacting the site
183 and telling them so, which improves their accessibility for everyone!
185 - Another reason could be that a page has a _huge_ amount of links. If that
186 bothers you regularly, feel free to send a pull request with faster code!
188 #### Filtering hints by element text
190 All characters other than the hint characters are used to filter hint markers by
193 The filtering works like in Firefox’s location bar. In short, that means:
195 - It is case insensitive.
196 - Your typed characters are split on spaces. Each part must be present in the
197 element text (in any order, and they may overlap).
199 By default, “f” is a hint character. If you type an “f”, that character is used
200 to match the hints on screen. If you type an “F” (uppercase), though, which is
201 _not_ a hint character by default, you will filter the hints based on element
202 text, causing some hints markers to disappear, and the rest to be replaced. Only
203 the markable elements with text containing an “f” or “F” will now get a hint
204 marker. All the “f”s and “F”s are highlighted on the page, to help you keep
205 track of what’s going on. Keep typing other non-hint characters to further
206 reduce the number of hint markers, and make the hints shorter all the time.
208 Hint markers are usually displayed in uppercase, because it looks nicer.
209 However, if you mix both lowercase and uppercase hint characters, they will be
210 displayed as-is, so you can tell them apart. It is recommended to either use
211 _only_ lowercase or _only_ uppercase characters, though.
213 Some people prefer to filter hint markers by element text in the first hand,
214 rather than typing hint characters. If so, it is a good idea to choose all
215 uppercase hint characters, or only numbers. This way, you can press `f` and then
216 simply begin typing the text of the link you wish to follow.
218 [hint commands]: commands.md#the-hint-commands--hints-mode
220 ### Hint auto-activation
222 The marker (or markers in the case where several links go to the same place and
223 have gotten the same hint) with the best hint are highlighted in a different
224 color. You may at any time press `<enter>` to activate those markers.
226 One workflow is to type non-hint characters until the hint marker of the element
227 you want to activate gets highlighted, and then hit `<enter>`. However, if _all_
228 hint markers end up highlighted (because the text you’ve typed uniquely
229 identifies a single link) the highlighted markers will be activated
232 If you dislike that, disable this option. Then, you either have to press
233 `<enter>` or a hint character to activate hint markers.
235 ### Auto-activation timeout
237 If you type quickly, you might find that you will keep typing even after a hint
238 marker has been automatically activated (see [Hint auto-activation]). You might
239 simply not react that quickly. This might cause you to accidentally trigger
240 VimFx commands. Therefore, VimFx ignores all your keypresses for a certain
241 number of milliseconds when having automatically activated a hint marker after
242 filtering by element text. This option controls exactly how many milliseconds
245 If you can’t find a timeout that works for you, you might want to disable [Hint
246 auto-activation] instead.
248 [Hint auto-activation]: #hint-auto-activation
252 The maximum amount of time (in milliseconds) that may pass between two
253 keypresses of a shortcut.
255 It’s easy to press, say, `a` by mistake while browsing. Without a timeout, you
256 might be surprised that all search results are highlighted when you a bit later
257 try to search using the `/` command. (That’s what `a/` does.) _With_ a timeout,
258 the `a` would be cancelled when the timeout has passed.
260 ### “Previous”/“Next” link patterns
262 Space separated lists of patterns that match links to the previous/next page.
263 Used by the `[` and `]` commands.
265 There is a standardized way for websites to tell browsers the URLs to the
266 previous and next page. VimFx looks for that information in the first place.
267 Unfortunately, many websites don’t provide this information. Then VimFx falls
268 back on looking for links on the page that seem to go to the previous/next page
271 The patterns are matched at the beginning and end of link text (and the
272 attributes defined by the advanced setting [`pattern_attrs`]). The patterns do
273 not match in the middle of words, so “previous” does not match “previously”.
274 The matching is case <strong>in</strong>sensitive.
276 Actually, the patterns are regular expressions. If you do not know what a
277 regular expression is, that’s fine. You can type simple patterns like the
278 default ones without problems. If you do know what it is, though, you have the
279 possibility to create more advanced patterns if needed.
281 Some of the default patterns are English words. You might want to add
282 alternatives in your own language.
284 Note: If you need to include a space in your pattern, use `\s`. For example:
287 [`pattern_attrs`]: #pattern_attrs
292 These options are _not_ available in VimFx’s settings page in the Add-ons
293 Manager. They can only be changed in [about:config] or using a [config file].
294 They all start with `extensions.VimFx.`.
296 (There are actually a few more advanced options than those listed here. You can
297 see them all in [defaults.coffee].)
299 [about:config]: http://kb.mozillazine.org/About:config
300 [config file]: config-file.md
301 [defaults.coffee]: ../extension/lib/defaults.coffee
303 ### `notifications_enabled`
305 Controls whether [notifications] should be shown or not.
307 You can also choose to show notifications any way you want by listening for the
308 [the `notification` and `hideNotification` events][notification-events].
310 [notifications]: notifications.md
311 [notification-events]: api.md#the-notification-and-hidenotification-events
313 ### `notify_entered_keys`
315 If enabled, a [notification] is shown with the keys you have entered so far of
316 a command. This is only noticeable if you type a multi-key shortcut or use a
317 count, or if you filter hint markers by element text (then, the text you’ve
318 typed will be shown).
320 [notification]: notifications.md
322 ### `prevent_target_blank`
324 You might have noticed that some links open in new tabs when you click them.
325 That is not the case if you “click” them using VimFx’s `f` command, though. If
326 you dislike that, disable this option.
330 Controls whether [counts] are enabled or not.
332 [counts]: commands.md#counts
334 ### `find_from_top_of_viewport`
336 Toggles whether the various find commands are Vim-style or Firefox
339 Disable this pref if you want `/` to work more like `<c-f>` and `n`/`N` to work
340 more like `<f3>`/`<s-f3>`.
342 If there is selected text on the page, Firefox starts searching after that.
343 VimFx does so too, but only if the selection is currently _visible_ (inside the
346 If there _isn’t_ selected text on the page, Firefox starts searching from the
347 top of the page. VimFx instead starts searching from the top of the current
350 The VimFx behavior is designed to be less disorienting. It is also similar to
351 how searching in Vim works. Again, you can return to the Firefox default
352 behavior (if you prefer that) by disabling this pref.
354 One of the main benefits of the VimFx behavior is that you can scroll past a
355 block of the text with lots of search matches and then continue going through
356 matches with `n` after that block, without having to spam `n` lots and lots of
359 ### `ignore_ctrl_alt`
361 This option is enabled by default on Windows, and disabled otherwise.
363 If enabled, ignores ctrl+alt for printable keys. `<a-c-$>` becomes `$` and
364 `<a-c-A>` becomes `A`, while `<a-c-enter>` stays the same.
366 This option is suitable on Windows, which treats [AltGr as
367 ctrl+alt][wikipedia-altgr]. For example, if a user of the sv-SE layout on
368 Windows holds AltGr and presses the key labeled `4`, in order to produce a `$`,
369 the result would be `<a-c-$>` without this option, making it impossible to
370 trigger a keyboard shortcut containing `$`. _With_ this option the result is
371 `$`, as expected (and as on GNU/Linux). On the other hand it won’t be possible
372 to trigger keyboard shortcuts such as `<a-c-a>`, but ctrl+alt keyboard shortcuts
373 are [discouraged on Windows][wikipedia-altgr] anyway because of this reason.
375 [wikipedia-altgr]: https://en.wikipedia.org/wiki/AltGr_key#Control_.2B_Alt_as_a_substitute
377 ### `prevent_autofocus_modes`
379 Space separated list of modes where `prevent_autofocus` should be used.
381 ### `config_file_directory`
383 VimFx can optionally be customized using a [config file]. If you want to that,
384 you need to tell VimFx where that file is. That’s what this pref is for.
386 By default this pref is blank (the empty string), which means that no config
387 file should be loaded.
389 If non-blank, it should be the path to the directory where the config file
390 exists. See the [config file] documentation for more information.
392 [config file]: config-file.md
396 The number of milliseconds VimFx should wait after an element has been blurred
397 before checking if you’re inside a text input or not.
399 Some sites with fancy text inputs (such as twitter) blur the text input for a
400 split second and then re-focus it again while typing (for some reason). If you
401 happen to press a key during that split second, that key might trigger a VimFx
402 shortcut instead of typing into the text input, which can be quite annoying. To
403 avoid the problem, VimFx waits a bit before checking if you have left the text
408 Apart from its own prefs, VimFx also respects a few built-in Firefox prefs.
410 #### Smooth scrolling
412 If you want to customize Firefox’s smooth scrolling, adjusting
413 `general.smoothScroll.{lines,pages,other}.duration{Min,Max}MS` is the way to
414 go. VimFx has similar prefs for the scrolling commands, but they work like
415 `layout.css.scroll-behavior.spring-constant`.
417 Basically, the higher the value, the faster the scrolling.
419 These are VimFx’s variants, and the commands they affect:
421 - `smoothScroll.lines.spring-constant`: `h`, `l`, `j`, `k`
422 - `smoothScroll.pages.spring-constant`: `d`, `u`, `<space>`, `<s-space>`
423 - `smoothScroll.other.spring-constant`: `gg`, `G`, `0`, `^`, `$`, `'`
425 Note that the value of these prefs are _strings,_ not numbers!
427 Unfortunately, Firefox provides no way for code to tell which “spring constant”
428 it wants when scrolling smoothly. All VimFx can do is to temporarily set
429 Firefox’s `layout.css.scroll-behavior.spring-constant` pref. It is reset again
430 after one second (by default). If that doesn’t work out for you, you can
431 customize that timeout using the `scroll.reset_timeout` pref.
433 The Firefox pref `general.smoothScroll` lets you turn off smooth scrolling
434 entirely, including all of VimFx’s scrolling commands.
436 `general.smoothScroll.lines`, `general.smoothScroll.pages`, and
437 `general.smoothScroll.other` lets you selectively disable smooth scrolling.
438 VimFx’s scrolling commands follow the same “lines,” “pages” and “other”
439 categorization as in the above list.
443 By default you can scroll using the arrow keys in Firefox. You can control how
444 much they scroll by adjusting the following prefs:
446 - `toolkit.scrollbox.horizontalScrollDistance`: `<left>`, `<right>`, `h`, `l`
447 - `toolkit.scrollbox.verticalScrollDistance`: `<down>`, `<up>`, `j`, `k`
449 (VimFx used to have a `scroll_step` pref, but is has been replaced by the
452 #### `scroll.full_page_adjustment` and `scroll.half_page_adjustment`
454 An important use case for scrolling a full page down is to read an entire page
455 (a window-full) of text, press `<space>` and then continue reading the next
456 page. However, if you can only see, say, _half_ of the height the last line,
457 pressing `<space>` would give you the other half, but reading only the top or
458 bottom parts of letters is difficult. Even if the lines happen to line up with
459 the window edge to not be sliced horizontally, it might feel disorienting
462 For this reason, both VimFx and Firefox by default scroll _about a line less
463 than a whole page_ when pressing `<space>`. This solves the sliced-last-line
464 problem, and provides some context on where you are in the text you’re reading.
466 These two prefs control how many pixels “about a line” actually means for the
467 different page scrolling commands.
469 - `scroll.full_page_adjustment`: `<space>, `<s-space>`
470 - `scroll.half_page_adjustment`: `d`, `u`
472 #### `scroll.last_position_mark`
474 The special mark for the [`'`][scroll-to-mark] command that takes you to the
477 [scroll-to-mark]: commands.md#marks-m-and-
479 ### `pattern_selector`
481 A CSS selector that targets candidates for a previous/next page link.
485 A space-separated list of attributes that the [“Previous”/“Next” link patterns]
486 should be matched against.
488 [“Previous”/“Next” link patterns]: #previousnext-link-patterns
490 ### `hints.matched_timeout`
492 The number of milliseconds a matched hint marker should stay on screen before
493 disappearing (or resetting).
497 In Hints mode, VimFx continually checks if the element for a hint marker has
498 moved. If so, the marker is moved as well. This pref controls how many
499 milliseconds VimFx should “sleep” between each check. The shorter, the more CPU
500 usage, the longer, the more stuttery marker movement.
502 The default value should work fine, but if you have a low-performing computer
503 and you notice bothering CPU usage during Hints mode you might want to raise the
506 Set it to -1 to disable the marker movement feature entirely.
508 ### `hints.match_text`
510 If you strongly dislike that typing non-[Hint characters] filters hint markers
511 by element text, disable this pref. (That’ll make things work like it did in
512 VimFx 0.18.x and older.)
514 [Hint characters]: #hint-characters
516 ### `hints.peek_through`
518 This pref doesn’t do much. If you’ve used custom [styling] to change which
519 modifier lets you peek through markers in [Hints mode], you might want to change
520 this pref as well. Otherwise VimFx’s Keyboard Shortcuts dialog will still tell
521 you to press shift for this task.
523 [styling]: styling.md
524 [Hints mode]: commands.md#the-hint-commands--hints-mode
526 ### `hints.toggle_in_tab`
528 If the keypress that matched a hint starts with this string, toggle whether to
529 open the matched link in the current tab or a new tab. See the [hint commands]
530 for more information.
532 ### `hints.toggle_in_background`
534 If the keypress that matched a hint starts with this string, open the matched
535 link in a new tab and toggle whether to open that tab in the background or
536 foreground. See the [hint commands] for more information.
538 ### `activatable_element_keys`
540 Keys that should not trigger VimFx commands but be sent through to the page if
541 an “activatable” element (link or button) is focused.
543 ### `adjustable_element_keys`
545 Keys that should not trigger VimFx commands but be sent through to the page if
546 an “adjustable” element (form control or video player) is focused.
548 ### `focus_previous_key` and `focus_next_key`
550 The default values are `<s-tab` and `<tab>`, respectively. Those keys are
551 specially handled after focusing a text input using [`gi`]. To disable this
552 special handling, set the prefs to the empty string.
554 [`gi`]: commands.md#gi-1
559 These options are available in neither VimFx’s settings page in the Add-ons
560 Manager nor in [about:config]. The only way to change them is by using the
565 See the description of the `translations` option in [vim-like-key-notation].
567 [vim-like-key-notation]: https://github.com/lydell/vim-like-key-notation#api
571 See the documentation for [`vimfx.get('categories')`][categories].
573 [categories]: api.md#vimfxgetcategories