### Install Dependencies and Build Production Version

Source: https://github.com/brookhong/surfingkeys/blob/master/CONTRIBUTING.md

Installs project dependencies and builds the production-ready version of the extension.

```bash
npm install
npm run build:prod
```

--------------------------------

### Example SurfingKeys Configuration URL

Source: https://github.com/brookhong/surfingkeys/wiki/Example-Configurations

This is an example URL for a SurfingKeys configuration file. It can be used to directly load a custom configuration.

```text
https://raw.githubusercontent.com/mindgitrwx/personal_configures/master/Surfingkeys-config-ko-dev.js
```

--------------------------------

### Mac/Linux Shell Script for Starting Neovim Host

Source: https://github.com/brookhong/surfingkeys/blob/master/src/nvim/server/Readme.md

This shell script is used on macOS and Linux to start Neovim in headless mode and load the Surfingkeys server script. It dynamically determines the script's path.

```shell
SCRIPT_PATH=$(dirname $BASH_SOURCE[0])
exec nvim --headless -c "luafile $SCRIPT_PATH/server.lua"
```

--------------------------------

### Jisho Inline Query Example

Source: https://github.com/brookhong/surfingkeys/wiki/Register-inline-query

Example of registering the Jisho dictionary service for Japanese-English translation. This snippet parses HTML and cleans up the DOM to display relevant information.

```javascript
api.Front.registerInlineQuery({
    url: function(q) {
        return `https://jisho.org/search/${q}`;
    },
    parseResult: function(res) {
        var parser = new DOMParser();
        var doc = parser.parseFromString(res.text, "text/html");
        var result = doc.querySelector("#primary>div.exact_block");
        if (result) {
            result.querySelectorAll('div>span.furigana').forEach(function(e){
                br = document.createElement("br");
                e.appendChild(br);
            });
            result.querySelectorAll('h4').forEach(function(e){
                e.remove();
            });
            result.querySelectorAll('div>div.concept_light-status').forEach(function(e){
                e.remove();
            });
            result.querySelectorAll('div>a.light-details_link').forEach(function(e){
                e.remove();
            });
            result.querySelectorAll('div>span.meaning-abstract').forEach(function(e){
                e.remove();
            });
            result.querySelectorAll('div>span.supplemental_info').forEach(function(e){
                e.outerHTML = " " + e.outerHTML;
            });
            var exp = result.innerHTML;
            return exp;
        }    }
});
```

--------------------------------

### Windows Batch Script for Starting Neovim Host

Source: https://github.com/brookhong/surfingkeys/blob/master/src/nvim/server/Readme.md

This batch script is used on Windows to start Neovim in headless mode and load the Surfingkeys server script. Ensure the paths to nvim.exe and server.lua are correctly set.

```batch
@echo off
d:\tools\Neovim\bin\nvim.exe --headless -c "luafile C:\Users\brook\.Surfingkeys_NativeMessagingHosts\server.lua"
```

--------------------------------

### Shanbay Inline Query Example

Source: https://github.com/brookhong/surfingkeys/wiki/Register-inline-query

Example of registering the Shanbay dictionary service for English-Chinese translation. This snippet parses JSON responses and formats pronunciations and definitions.

```javascript
api.Front.registerInlineQuery({
    url: "https://api.shanbay.com/bdc/search/?word=",
    parseResult: function(res) {
        try {
            res = JSON.parse(res.text);
            var exp = res.msg;
            if (res.data.definition) {
                var pronunciations = [];
                for (var reg in res.data.pronunciations) {
                    pronunciations.push(`<div>[${reg}] ${res.data.pronunciations[reg]}</div>`);
                    // pronunciations.push(`<div><audio src="${res.data[reg+'_audio']}" controls></audio></div>`);
                }
                var definition = res.data.definition.split("\n").map(function(d) {
                    return `<li>${d}</li>`;
                }).join("");
                exp = `${pronunciations.join("")}<ul>${definition}</ul>`;
            }
            if (res.data.en_definitions) {
                exp += "<hr/>";
                for (var lex in res.data.en_definitions) {
                    var sense = res.data.en_definitions[lex].map(function(s) {
                        return `<li>${s}</li>`;
                    }).join("");
                    exp += `<div>${lex}</div><ul>${sense}</ul>`;
                }
            }
            return exp;
        } catch (e) {
            return "";
        }
    }
});
```

--------------------------------

### Youdao Inline Query Example

Source: https://github.com/brookhong/surfingkeys/wiki/Register-inline-query

Example of registering the Youdao dictionary service. This snippet uses DOMParser to parse HTML responses and extract relevant translation information.

```javascript
api.Front.registerInlineQuery({
    url: function(q) {
        return `http://dict.youdao.com/w/eng/${q}/#keyfrom=dict2.index`;
    },
    parseResult: function(res) {
        var parser = new DOMParser();
        var doc = parser.parseFromString(res.text, "text/html");
        var collinsResult = doc.querySelector("#collinsResult");
        var authTransToggle = doc.querySelector("#authTransToggle");
        var examplesToggle = doc.querySelector("#examplesToggle");
        if (collinsResult) {
            collinsResult.querySelectorAll("div>span.collinsOrder").forEach(function(span) {
                span.nextElementSibling.prepend(span);
            });
            collinsResult.querySelectorAll("div.examples").forEach(function(div) {
                div.innerHTML = div.innerHTML.replace(/<p/gi, "<span").replace(/<\/p>/gi, "</span>");
            });
            var exp = collinsResult.innerHTML;
            return exp;
        } else if (authTransToggle) {
            authTransToggle.querySelector("div.via.ar").remove();
            return authTransToggle.innerHTML;
        } else if (examplesToggle) {
            return examplesToggle.innerHTML;
        }
    }
});
```

--------------------------------

### Set Styles for Hints

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Applies custom CSS styles to hints. The first example sets general hint styles, while the second applies specific styles to hints in 'text' mode.

```javascript
Hints.style('border: solid 3px #552a48; color:#efe1eb; background: none; background-color: #552a48;');
```

```javascript
Hints.style("div{border: solid 3px #707070; color:#efe1eb; background: none; background-color: #707070;} div.begin{color:red;}", "text");
```

--------------------------------

### Update mapkey usage with api object

Source: https://github.com/brookhong/surfingkeys/wiki/Migrate-your-settings-from-0.9.74-to-1.0

Use the `api` prefix for functions like `mapkey` in version 1.0. This example shows the new required syntax.

```javascript
api.mapkey('<Ctrl-y>', 'Show me the money', function() {
    api.Front.showPopup('a well-known phrase uttered by characters in the 1996 film Jerry Maguire (Escape to close).');
});
```

--------------------------------

### Map Key for LLM Chat with System Prompt

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Assign a keybinding to open the LLM chat with a custom system prompt, for example, to act as a translator.

```javascript
api.mapkey('A', '#8Open llm chat', function() {
        api.Front.openOmnibar({type: "LLMChat", extra: {
            system: "You're a translator, whenever you got a message in Chinese, please just translate it into English, and if you got a message in English, please translate it to Chinese. You don't need to answer any question, just TRANSLATE."
        }});
    });
```

--------------------------------

### Set Custom Hint Characters

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Customize the characters used for link hints in Hints mode. This example sets characters for right-hand usage.

```javascript
api.Hints.setCharacters('yuiophjklnm'); // for right hand
```

--------------------------------

### Configure Emoji Completion Start

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Set the number of characters to type after a colon before emoji suggestions appear. Setting to 0 shows suggestions immediately after the colon.

```javascript
settings.startToShowEmoji = 0;
```

--------------------------------

### ACE Editor Theming with CSS Variables

Source: https://github.com/brookhong/surfingkeys/wiki/Home

Customize the appearance of the ACE editor within Surfingkeys using CSS variables. This example demonstrates how to set background, foreground, and cursor colors, including transparency.

```css
settings.theme= `
:root {
    --theme-ace-bg:#282828ab; /*Note the fourth channel, this adds transparency*/
    --theme-ace-bg-accent:#3c3836;
    --theme-ace-fg:#ebdbb2;
    --theme-ace-fg-accent:#7c6f64;
    --theme-ace-cursor:#928374;
    --theme-ace-select:#458588;
}
#sk_editor {
    height: 50% !important; /*Remove this to restore the default editor size*/
    background: var(--theme-ace-bg) !important;
}
.ace_dialog-bottom{
    border-top: 1px solid var(--theme-ace-bg) !important;
}
.ace-chrome .ace_print-margin, .ace_gutter, .ace_gutter-cell, .ace_dialog{
    background: var(--theme-ace-bg-accent) !important;
}
.ace-chrome{
    color: var(--theme-ace-fg) !important;
}
.ace_gutter, .ace_dialog {
    color: var(--theme-ace-fg-accent) !important;
}
.ace_cursor{
    color: var(--theme-ace-cursor) !important;
}
.normal-mode .ace_cursor{
    background-color: var(--theme-ace-cursor) !important;
    border: var(--theme-ace-cursor) !important;
}
.ace_marker-layer .ace_selection {
    background: var(--theme-ace-select) !important;
} `
```

--------------------------------

### Remap Omnibar Tab Navigation

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Customize key bindings for navigating through omnibar candidates. These examples map Ctrl-n to Tab and Ctrl-p to Shift-Tab.

```javascript
api.cmap('<Ctrl-n>', '<Tab>');
```

```javascript
api.cmap('<Ctrl-p>', '<Shift-Tab>');
```

--------------------------------

### Set Styles for Visual Mode Marks and Cursor

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Customizes the appearance of marks and the cursor within visual mode. The first example styles the marks, and the second styles the cursor.

```javascript
Visual.style('marks', 'background-color: #89a1e2;');
```

```javascript
Visual.style('cursor', 'background-color: #9065b7;');
```

--------------------------------

### Create and Open Sessions

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Use commands to create, open, list, and delete named sessions. Sessions save and restore lists of URLs.

```text
createSession works
```

```text
openSession works
```

```text
listSession
```

```text
deleteSession works
```

--------------------------------

### Hints.create

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Creates hints for elements to click. It takes a CSS selector or an array of HTMLElements and a callback function to execute when a hint key is pressed.

```APIDOC
## Hints.create

*   **See**: Hints.dispatchMouseClick

Create hints for elements to click.

### Parameters

*   `cssSelector`  `string or array of HTMLElement`, if `links` is a string, it will be used as css selector.
*   `onHintKey` **[function][108]** a callback function on hint keys pressed.
*   `attrs` **[object][109]** `active`: whether to activate the new tab when a link is opened, `tabbed`: whether to open a link in a new tab, `multipleHits`: whether to stay in hints mode after one hint is triggered. (optional, default `null`)

### Examples

```javascript
mapkey('yA', '#7Copy a link URL to the clipboard', function() {
    Hints.create('*[href]', function(element) {
        Clipboard.write('[' + element.innerText + '](' + element.href + ')');
    });
});
```

Returns **[Promise][113]** which will be resolved how many hints are created.
```

--------------------------------

### Markdown Preview from Clipboard

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Copy markdown to clipboard, then press ;pm to open a preview. Press ;pm again to edit the source in Vim.

```vim
;pm
```

--------------------------------

### Create Vim-like Marks

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Press `m` followed by a character (0-9, a-z, A-Z) to create a mark pointing to the current URL. Use `'` followed by the mark name to jump to the bookmarked page.

```Surfingkeys
ma
```

```Surfingkeys
'a
```

--------------------------------

### Get Browser Tabs

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Calls a background action to retrieve information about open tabs in the current window. The response is logged to the console.

```javascript
RUNTIME('getTabs', {queryInfo: {currentWindow: true}}, response => {
  console.log(response);
});
```

--------------------------------

### View All Vim-like Marks

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Press `om` to display all created vim-like marks.

```Surfingkeys
om
```

--------------------------------

### Open Omnibar for Commands

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Press `:` to open the omnibar for executing pre-defined commands. Results are displayed below the omnibar.

```Surfingkeys
:setProxyMode always
```

```Surfingkeys
:setProxyMode byhost
```

```Surfingkeys
:setProxyMode direct
```

--------------------------------

### Front.showEditor

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Launches the vim editor for editing elements or content. It supports specifying the editor type and using Neovim.

```APIDOC
## Front.showEditor

Launch the vim editor.

### Parameters

*   `element` **[HTMLElement][112]** the target element which the vim editor is launched for, this parameter can also be a string, which will be used as default content in vim editor.
*   `onWrite` **[function][108]** a callback function to be executed on written back from vim editor.
*   `type` **[string][107]** the type for the vim editor, which can be `url`, if not provided, it will be tag name of the target element. (optional, default `null`)
*   `useNeovim` **[boolean][111]** the vim editor will be the embeded JS implementation, if `useNeovim` is true, neovim will be used through natvie messaging. (optional, default `false`)

### Examples

```javascript
mapkey(';U', '#4Edit current URL with vim editor, and reload', function() {
    Front.showEditor(window.location.href, function(data) {
        window.location.href = data;
    }, 'url');
});
```
```

--------------------------------

### Remap Lurk Mode Activation

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Change the key binding to activate normal mode from lurk mode. This example maps Alt-j to the default Alt-i.

```javascript
api.lmap("<Alt-j>", "<Alt-i>");
```

--------------------------------

### Get Large Visible Elements

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Retrieves elements that occupy a significant portion of the viewport. Default minimum dimensions are 30% of viewport width and height.

```javascript
// Get elements that are at least 30% of viewport dimensions
var largeElements = getLargeElements();

// Get elements that are at least 50% of viewport dimensions
var veryLargeElements = getLargeElements(0.5, 0.5);
```

--------------------------------

### Create Shortcut for Set Proxy Command

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Map custom keybindings to execute specific commands, such as setting proxy modes.

```JavaScript
api.map(';pa', ':setProxyMode always');
```

```JavaScript
api.map(';pb', ':setProxyMode byhost');
```

```JavaScript
api.map(';pd', ':setProxyMode direct');
```

--------------------------------

### Build Development Version

Source: https://github.com/brookhong/surfingkeys/blob/master/CONTRIBUTING.md

Builds the development version of the extension, useful for debugging and local testing.

```bash
npm run build:dev
```

--------------------------------

### Proxy Mode Shortcuts

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Provides convenient shortcuts for setting common proxy modes.

```text
;pa
```

```text
;pb
```

```text
;pc
```

```text
;pd
```

```text
;ps
```

--------------------------------

### Copy Link URL to Clipboard with Hints.create

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Maps the 'yA' key to copy a link URL to the clipboard. It creates hints for all elements with an href attribute and uses a callback to format and write the link to the clipboard.

```javascript
mapkey('yA', '#7Copy a link URL to the clipboard', function() {
    Hints.create('*[href]', function(element) {
        Clipboard.write('[' + element.innerText + '](' + element.href + ')');
    });
});
```

--------------------------------

### Github Light Theme and Hint Styling

Source: https://github.com/brookhong/surfingkeys/wiki/Color-Themes

Applies the Github light theme and customizes hint styles using JavaScript. This includes setting font properties, colors, and background for hints and the main UI theme.

```javascript
const hintsCss =
  "font-size: 12pt; font-family: JetBrains Mono NL, Cascadia Code, SauceCodePro Nerd Font, Consolas, Menlo, monospace; border: 0px; color: #0366d6; background: initial; background-color: #ffffff";

api.Hints.style(hintsCss);
api.Hints.style(hintsCss, "text");

settings.theme = `
.sk_theme {
  font-family: JetBrains Mono NL, Cascadia Code, SauceCodePro Nerd Font, Consolas, Menlo, monospace;
  font-size: 10pt;
  background: #ffffff;
  color: #24292f;
}
.sk_theme tbody {
  color: #ffffff;
}
.sk_theme input {
  color: #24292f;
}
.sk_theme .url {
  color: #24292f;
}
.sk_theme .annotation {
  color: #24292f;
}
.sk_theme .omnibar_highlight {
  color: #24292f;
}
.sk_theme #sk_omnibarSearchResult ul li:nth-child(odd) {
  background: #ffffff;
}
.sk_theme #sk_omnibarSearchResult ul li.focused {
  background: #0598bc;
}
#sk_status,
#sk_find {
  font-size: 10pt;
}
`;
```

--------------------------------

### Get Clickable Elements with Custom Selectors

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Finds clickable elements using an optional CSS selector and a regular expression to match element text. Useful for elements SurfingKeys might not identify by default.

```javascript
var elms = getClickableElements("[rel=link]", /click this/);
```

--------------------------------

### RUNTIME

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Calls a background action with specified arguments and executes a callback with the response. Used for interacting with background browser functionalities.

```APIDOC
## RUNTIME

### Description
Call background `action` with `args`, the `callback` will be executed with response from background.

### Parameters
* `action` **[string]** - A background action to be called.
* `args` **[object]** - The parameters to be passed to the background action.
* `callback` **[function]** - A function to be executed with the result from the background action.

### Examples
```javascript
RUNTIME('getTabs', {queryInfo: {currentWindow: true}}, response => {
  console.log(response);
});
```
```

--------------------------------

### Create Vim-like Marks from Bookmarks

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Hold Ctrl + Shift while pressing a mark name (e.g., `f`) after locating a URL in the bookmarks to create a persistent mark.

```Surfingkeys
Ctrl+Shift+f
```

--------------------------------

### Jump to URL from Bookmark Mark

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Press `'` followed by the uppercase mark name (e.g., `'F`) to directly open the URL associated with that bookmark mark.

```Surfingkeys
'F
```

--------------------------------

### Front.openOmnibar

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Opens the omnibar with various predefined types for searching and navigation.

```APIDOC
## Front.openOmnibar

Open the omnibar.

### Parameters

*   `args` **[object][109]** `type` the sub type for the omnibar, which can be `Bookmarks`, `AddBookmark`, `History`, `URLs`, `RecentlyClosed`, `TabURLs`, `Tabs`, `Windows`, `VIMarks`, `SearchEngine`, `Commands`, `OmniQuery` and `UserURLs`.
```

--------------------------------

### Hints.style

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Sets styles for hints. It can apply general styles or specific styles for hints mode when entering visual mode.

```APIDOC
## Hints.style

Set styles for hints.

### Parameters

*   `css` **[string][107]** styles for hints.
*   `mode` **[string][107]** sub mode for hints, use `text` for hints mode to enter visual mode. (optional, default `null`)

### Examples

```javascript
Hints.style('border: solid 3px #552a48; color:#efe1eb; background: none; background-color: #552a48;');
Hints.style("div{border: solid 3px #707070; color:#efe1eb; background: none; background-color: #707070;} div.begin{color:red;}", "text");
```
```

--------------------------------

### Build Firefox Production Extension

Source: https://github.com/brookhong/surfingkeys/blob/master/CONTRIBUTING.md

Builds the production version of the extension specifically for Firefox.

```bash
browser=firefox npm run build:prod
```

--------------------------------

### Style Hints and Visual Hints

Source: https://github.com/brookhong/surfingkeys/wiki/Color-Themes

Applies custom styles to hints and visual hints. Use the first style for regular hints and the second for text hints. Ensure the font is available.

```javascript
api.Hints.style('border: solid 1px #3D3E3E; color:#F92660; background: initial; background-color: #272822; font-family: Maple Mono Freeze; box-shadow: 3px 3px 5px rgba(0, 0, 0, 0.8);');
api.Hints.style("border: solid 1px #3D3E3E !important; padding: 1px !important; color: #A6E22E !important; background: #272822 !important; font-family: Maple Mono Freeze !important; box-shadow: 3px 3px 5px rgba(0, 0, 0, 0.8) !important;", "text");
```

--------------------------------

### Run Ollama with Modified Origins (Windows)

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Command to run Ollama on Windows, allowing it to serve requests from Chrome extensions.

```bash
OLLAMA_ORIGINS=chrome-extension://* ollama serve
```

--------------------------------

### Configure LLM Provider Settings

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Set the default LLM provider and configure credentials/API keys for various services like Bedrock, Gemini, and Ollama.

```javascript
settings.defaultLLMProvider = "bedrock";
    settings.llm = {
        bedrock: {
            accessKeyId: '********************',
            secretAccessKey: '****************************************',
            // model: 'anthropic.claude-3-5-sonnet-20241022-v2:0',
            model: 'us.anthropic.claude-3-7-sonnet-20250219-v1:0',
        },
        gemini: {
            apiKey: '***************************************',
        },
        ollama: {
            model: 'qwen2.5-coder:32b',
        },
        deepseek: {
            apiKey: '***********************************',
            model: 'deepseek-chat',
        },
        custom: {
            serviceUrl: 'https://api.siliconflow.cn/v1/chat/completions',
            apiKey: '***********************************',
            model: 'deepseek-ai/DeepSeek-V3.1',
        }
    };
```

--------------------------------

### Set Proxy Server

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Configure the proxy server for Surfingkeys. Supports direct IP:Port or SOCKS5 proxy configurations.

```text
setProxy 192.168.1.100:8080
```

```text
setProxy 127.0.0.1:1080 SOCKS5
```

--------------------------------

### vmapkey

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Creates a keyboard shortcut in visual mode, similar to `mapkey`. It allows defining key sequences, annotations, and JavaScript functions for visual mode actions, with optional domain and repeat ignore settings.

```APIDOC
## vmapkey

### Description
Create a shortcut in visual mode to execute your own action.

### Parameters
* `keys` **[string]** the key sequence for the shortcut.
* `annotation` **[string]** a help message to describe the action, which will displayed in help opened by `?`.
* `jscode` **[function]** a Javascript function to be bound. If the function needs an argument, next pressed key will be fed to the function.
* `options` **[object]** `domain`: regex, a Javascript regex pattern to identify the domains that this mapping works, for example, `/github.com/i` says that this mapping works only for github.com, `repeatIgnore`: boolean, whether this action can be repeated by dot command. (optional, default `null`)

### See
* mapkey
```

--------------------------------

### Edit Settings with Vim

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Press ;e to open the settings editor. Press :w to save settings.

```vim
;e
```

```vim
:w
```

--------------------------------

### Build Development Version for Firefox

Source: https://github.com/brookhong/surfingkeys/blob/master/CONTRIBUTING.md

Builds the development version of the extension specifically for Firefox.

```bash
browser=firefox npm run build:dev
```

--------------------------------

### Refresh Markdown Preview

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

On the markdown preview page, press :wq to refresh the preview with saved changes.

```vim
:wq
```

--------------------------------

### Map Key for Clicking Images on Weibo

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Maps the 'q' key to click on images within a specified domain (weibo.com). It uses Hints.create to select image elements and Hints.dispatchMouseClick to trigger the click.

```javascript
mapkey('q', 'click on images', function() {
    Hints.create("div.media_box img", Hints.dispatchMouseClick);
}, {domain: /weibo.com/i});
```

--------------------------------

### Hints.click

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Clicks on an element or generates hints for clickable elements. It can force a click on the first input element if multiple are found.

```APIDOC
## Hints.click

Click element or create hints for elements to click.

### Parameters

* `links`  `string or array of HTMLElement`, click on it if there is only one in the array or `force` parameter is true, otherwise hints will be generated for them. If `links` is a string, it will be used as css selector for `getClickableElements`.
* `force` **[boolean][111]** force to click the first input element whether there are more than one elements in `links` or not. (optional, default `false`)

### Examples

```javascript
mapkey('zz', 'Hide replies', function() {
    Hints.click(document.querySelectorAll("#less-replies:not([hidden])"), true);
});
```
```

--------------------------------

### Custom Key Mappings for Surfingkeys

Source: https://github.com/brookhong/surfingkeys/wiki/Home

Define custom key mappings to replicate behaviors from extensions like Vimium or to create custom shortcuts. This snippet shows how to map single keys, key sequences, and trigger functions.

```javascript
map('u', 'e');
mapkey('p', "Open the clipboard's URL in the current tab", function() {
    Front.getContentFromClipboard(function(response) {
        window.location.href = response.data;
    });
});
map('P', 'cc');
map('gi', 'i');
map('F', 'gf');
map('gf', 'w');
map('`', "'");
// save default key `t` to temp key `>_t`
map('>_t', 't');
// create a new key `t` for default key `on`
map('t', 'on');
// create a new key `o` for saved temp key `>_t`
map('o', '>_t');
map('H', 'S');
map('L', 'D');
map('gt', 'R');
map('gT', 'E');
map('K', 'R');
map('J', 'E');
```

--------------------------------

### Windows JSON Configuration for Native Messaging Host

Source: https://github.com/brookhong/surfingkeys/blob/master/src/nvim/server/Readme.md

This JSON file configures the Surfingkeys native messaging host for Chrome/Chromium on Windows. It specifies allowed origins, a description, name, type, and the path to the startup script.

```json
{
    "allowed_origins": [
        "chrome-extension://aajlcoiaogpknhgninhopncaldipjdnp/",
        "chrome-extension://gfbliohnnapiefjpjlpjnehglfpaknnc/"
    ],
    "description": "Neovim UI client from Surfingkeys",
    "name": "surfingkeys",
    "type": "stdio",
    "path": "C:\\Users\brook\.Surfingkeys_NativeMessagingHosts\start.bat"
}
```

--------------------------------

### Mac/Linux JSON Configuration for Native Messaging Host

Source: https://github.com/brookhong/surfingkeys/blob/master/src/nvim/server/Readme.md

This JSON file configures the Surfingkeys native messaging host for Chromium-based browsers on macOS and Linux. It specifies allowed origins, description, name, type, and the path to the startup script.

```json
{
    "allowed_origins": [
        "chrome-extension://aajlcoiaogpknhgninhopncaldipjdnp/",
        "chrome-extension://gfbliohnnapiefjpjlpjnehglfpaknnc/"
    ],
    "description": "Neovim UI client from Surfingkeys",
    "name": "surfingkeys",
    "type": "stdio",
    "path": "<PATH_TO_YOUR_START_SH>/start.sh"
}
```

--------------------------------

### Gather All Tabs into Current Window

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Press `;gw` to gather all tabs from all windows into the current window.

```Surfingkeys
;gw
```

--------------------------------

### addVimMapKey

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Adds a key map in the ACE editor. Allows for complex key mappings by providing multiple configuration objects.

```APIDOC
## addVimMapKey

### Description
Add map key in ACE editor.

### Parameters
* `objects` **[object]** - Multiple objects to define key map in ACE, see more from [ace/keyboard/vim.js][116]

### Examples
```javascript
addVimMapKey(
    {
        keys: 'n',
        type: 'motion',
        motion: 'moveByCharacters',
        motionArgs: {
            forward: false
        }
    },

    {
        keys: 'e',
        type: 'motion',
        motion: 'moveByLines',
        motionArgs: {
            forward: true,
            linewise: true
        }
    }
);
```
```

--------------------------------

### Neovim Overlay CSS

Source: https://github.com/brookhong/surfingkeys/blob/master/src/pages/neovim.html

CSS styles for the Neovim overlay and background when integrated with SurfingKeys.

```css
#overlay { position: fixed; left: 20%; top: 20%; width: 50%; max-height: 50%; padding: 5%; background: #fafafa; box-shadow: 0px 2px 10px rgba(0, 0, 0, 0.8); z-index: 10; display: none; }
#background { position: fixed; left: 0; top: 0; width: 100%; height: 100%; background: #0e0e0ede; z-index: 9; display: none; }
body.neovim-disabled>#overlay, body.neovim-disabled>#background { display: block; }
```

--------------------------------

### Normal.passThrough

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Enters PassThrough mode, allowing direct input. It can optionally have a timeout.

```APIDOC
## Normal.passThrough

Enter PassThrough mode.

### Parameters

*   `timeout` **[number][114]?** how many milliseconds to linger in PassThrough mode, to ignore it will stay in PassThrough mode until an Escape key is pressed.
```

--------------------------------

### Normal.jumpVIMark

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Jumps to a specified vim-like mark within the document.

```APIDOC
## Normal.jumpVIMark

Jump to a vim-like mark.

### Parameters

*   `mark` **[string][107]** a vim-like mark.
```

--------------------------------

### Hints.setNumeric

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Enables numeric labels for link hints, allowing users to type numbers to activate hints.

```APIDOC
## Hints.setNumeric

### Description
Enables numeric labels for link hints, allowing users to type numbers to activate hints.

### Request Example
```javascript
Hints.setNumeric();
```
```

--------------------------------

### Show All Opened Tabs Overlay

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Press `T` to display an overlay of all open tabs. Press the hint character to switch to the corresponding tab.

```Surfingkeys
T
```

--------------------------------

### Zenbonse Hint Styling

Source: https://github.com/brookhong/surfingkeys/wiki/Color-Themes

Styles hints for the Zenbonse theme using JavaScript. It sets font properties and background for regular hints and text hints.

```javascript
const hintsCss =
  "font-size: 10pt; font-family: SauceCodePro Nerd Font, Consolas, Menlo, monospace; border: 0px; color:#2c363c; background: initial; background-color: #f0edec;";

api.Hints.style(hintsCss);
api.Hints.style(hintsCss, "text");
```

--------------------------------

### Move Current Tab to Selected Window

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Press `W` to bring up a popup of windows. Select a window and press Enter to move the current tab to it. If only one window exists, it creates a new window.

```Surfingkeys
W
```

--------------------------------

### Configure Markdown Parser

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

To use GitHub's markdown API instead of the local parser, set 'settings.useLocalMarkdownAPI = false;' in your settings.

```javascript
settings.useLocalMarkdownAPI = false;
```

--------------------------------

### Capture Current Page

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Press 'yg' to capture the current visible page.

```vim
yg
```

--------------------------------

### CSS for Overflow-Y and Body Styling

Source: https://github.com/brookhong/surfingkeys/blob/master/tests/data/too-low-buttons-2294.html

Sets initial styles for margin, padding, and body layout. Ensures buttons are at the bottom and spaced out.

```css
Overflow-Y Examples * { margin: 0; padding: 0; }
body { position: absolute; bottom: 0; width: 100vw; display: flex; flex-direction: row; align-items: flex-end; justify-content: space-around; }
```

--------------------------------

### imapkey

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Creates a keyboard shortcut in insert mode, analogous to `mapkey`. It enables the definition of key sequences, annotations, and JavaScript functions for actions performed while in insert mode, with support for domain and repeat ignore options.

```APIDOC
## imapkey

### Description
Create a shortcut in insert mode to execute your own action.

### Parameters
* `keys` **[string]** the key sequence for the shortcut.
* `annotation` **[string]** a help message to describe the action, which will displayed in help opened by `?`.
* `jscode` **[function]** a Javascript function to be bound. If the function needs an argument, next pressed key will be fed to the function.
* `options` **[object]** `domain`: regex, a Javascript regex pattern to identify the domains that this mapping works, for example, `/github.com/i` says that this mapping works only for github.com, `repeatIgnore`: boolean, whether this action can be repeated by dot command. (optional, default `null`)

### See
* mapkey
```

--------------------------------

### mapkey

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Creates a keyboard shortcut in normal mode to execute a custom JavaScript action. It allows specifying key sequences, annotations, the JavaScript function to run, and optional domain restrictions or repeat ignore settings.

```APIDOC
## mapkey

### Description
Create a shortcut in normal mode to execute your own action.

### Parameters
* `keys` **[string]** the key sequence for the shortcut.
* `annotation` **[string]** a help message to describe the action, which will displayed in help opened by `?`.
* `jscode` **[function]** a Javascript function to be bound. If the function needs an argument, next pressed key will be fed to the function.
* `options` **[object]** `domain`: regex, a Javascript regex pattern to identify the domains that this mapping works, for example, `/github.com/i` says that this mapping works only for github.com, `repeatIgnore`: boolean, whether this action can be repeated by dot command. (optional, default `null`)

### Request Example
```javascript
mapkey("<Space>", "pause/resume on youtube", function() {
    var btn = document.querySelector("button.ytp-ad-overlay-close-button") || document.querySelector("button.ytp-ad-skip-button") || document.querySelector('ytd-watch-flexy button.ytp-play-button');
    btn.click();
}, {domain: /youtube.com/i});
```
```

--------------------------------

### Normal.feedkeys

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Feeds keys into Normal mode, simulating keyboard input.

```APIDOC
## Normal.feedkeys

Feed keys into Normal mode.

### Parameters

*   `keys` **[string][107]** the keys to be fed into Normal mode.
```

--------------------------------

### Visual.style

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Sets styles for visual mode, allowing customization of marks and cursor appearance.

```APIDOC
## Visual.style

Set styles for visual mode.

### Parameters

*   `element` **[string][107]** element in visual mode, which can be `marks` and `cursor`.
*   `style` **[string][107]** css style

### Examples

```javascript
Visual.style('marks', 'background-color: #89a1e2;');
Visual.style('cursor', 'background-color: #9065b7;');
```
```

--------------------------------

### Gather Filtered Tabs into Current Window

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Use `;gt` to open the omnibar with tabs from other windows. Filter them by inputting text, then press Enter to move the filtered tabs to the current window.

```Surfingkeys
;gt
```

--------------------------------

### Toggle Original PDF Viewer

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Press ';s' to toggle between Surfingkeys' integrated PDF viewer and Chrome's original PDF viewer.

```vim
;s
```

--------------------------------

### Add Domain-Specific Settings

Source: https://github.com/brookhong/surfingkeys/wiki/FAQ

Use this snippet to enable specific settings like `smartPageBoundary` for a particular domain, such as Google.

```javascript
if ( document.origin === "https://www.google.com" ) {
    settings.smartPageBoundary = true;
}
```

--------------------------------

### Create a New Key Mapping

Source: https://github.com/brookhong/surfingkeys/blob/master/src/pages/options.html

Use `api.mapkey` to create a new custom key mapping with a descriptive name and an associated action. The action can be a simple function call.

```javascript
api.mapkey('<Ctrl-y>', 'Show me the money', function() { api.Front.showPopup('a well-known phrase uttered by characters in the 1996 film Jerry Maguire (Escape to close).'); });
```

--------------------------------

### Toggle Proxy for Current Site

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Toggles the proxy setting for the current website.

```text
cp
```

--------------------------------

### Search Selected Text with Google

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Press `sg` to search selected text with Google. If no text is selected, it searches the system clipboard. In visual mode, it searches the selected text.

```Surfingkeys
sg
```

--------------------------------

### Front.showBanner

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Displays a message in a banner at the top of the screen. The banner can be configured to disappear after a specified timeout.

```APIDOC
## Front.showBanner

### Description
Show message in banner.

### Parameters
* `msg` **[string]** - The message to be displayed in banner.
* `timeout` **[number]** (optional, default `1600`) - Milliseconds after which the banner will disappear.

### Examples
```javascript
Front.showBanner(window.location.href);
```
```

--------------------------------

### Enable Numeric Hints

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Enables the use of numeric digits as hint labels for clickable elements on the page. This replaces the older `Hints.numericHints = true;` setting.

```javascript
Hints.setNumeric();
```

--------------------------------

### Set Theme Settings

Source: https://github.com/brookhong/surfingkeys/blob/master/src/pages/options.html

Customize the appearance of Surfingkeys by defining CSS styles for various elements. These settings are applied when the theme is active.

```javascript
settings.theme = 
`.sk_theme { font-family: Input Sans Condensed, Charcoal, sans-serif;
 font-size: 10pt;
 background: #24272e;
 color: #abb2bf;
 }

.sk_theme tbody { color: #fff; }
.sk_theme input { color: #d0d0d0; }
.sk_theme .url { color: #61afef; }
.sk_theme .annotation { color: #56b6c2; }
.sk_theme .omnibar_highlight { color: #528bff; }
.sk_theme .omnibar_timestamp { color: #e5c07b; }
.sk_theme .omnibar_visitcount { color: #98c379; }

.sk_theme #sk_omnibarSearchResult ul li:nth-child(odd) { background: #303030; }
.sk_theme #sk_omnibarSearchResult ul li.focused { background: #3e4452; }

#sk_status, #sk_find { font-size: 20pt; }
`;
```

--------------------------------

### Open AWS Services in Omnibar

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Maps a key sequence to open a list of AWS services in the omnibar. It dynamically fetches service titles and URLs from the current AWS console page.

```javascript
mapkey('ou', '#8Open AWS services', function() {
    var services = Array.from(top.document.querySelectorAll('#awsc-services-container li[data-service-href]')).map(function(li) {
        return {
            title: li.querySelector("span.service-label").textContent,
            url: li.getAttribute('data-service-href')
        };
    });
    if (services.length === 0) {
        services = Array.from(top.document.querySelectorAll('div[data-testid="awsc-nav-service-list"] li[data-testid]>a')).map(function(a) {
            return {
                title: a.innerText,
                url: a.href
            };
        });
    }
    Front.openOmnibar({type: "UserURLs", extra: services});
}, {domain: /console.amazonaws|console.aws.amazon.com/i});
```

--------------------------------

### Alias api functions for backward compatibility

Source: https://github.com/brookhong/surfingkeys/wiki/Migrate-your-settings-from-0.9.74-to-1.0

Add this snippet at the beginning of your settings to avoid modifying existing code that uses functions without the `api` prefix. It destructures commonly used API functions into local constants.

```javascript
const {
    aceVimMap,
    mapkey,
    imap,
    imapkey,
    getClickableElements,
    vmapkey,
    map,
    unmap,
    unmapAllExcept,
    vunmap,
    cmap,
    addSearchAlias,
    removeSearchAlias,
    tabOpenLink,
    readText,
    Clipboard,
    Front,
    Hints,
    Visual,
    RUNTIME
} = api;
```

--------------------------------

### Hints.dispatchMouseClick

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Dispatches a mouse click event on a specified HTML element, typically used as a default handler for hint activation.

```APIDOC
## Hints.dispatchMouseClick

### Description
Dispatches a mouse click event on a specified HTML element, typically used as a default handler for hint activation.

### Parameters
* `element` **[HTMLElement]** the element for which the pressed hint is targeted.

### Note
* **See**: Hints.create
```

--------------------------------

### Front.registerInlineQuery

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Registers an inline query with the specified arguments. This allows for custom dictionary services and parsing of results.

```APIDOC
## Front.registerInlineQuery

### Description
Register an inline query. This function allows you to define custom dictionary services and how their results should be parsed and displayed.

### Parameters
* `args` **[object]** - An object containing the configuration for the inline query.
  * `url` (string or function) - The URL of the dictionary service or a function that returns the URL.
  * `parseResult` (function) - A function to parse the result from the dictionary service and return an HTML string for rendering.
  * `headers` (object, optional) - Optional headers to be included in the request, useful for authentication.
```

--------------------------------

### Open Omnibar for Tab Selection

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Map the spacebar to open the omnibar for selecting tabs, providing an alternative to the default tab overlay.

```JavaScript
api.mapkey('<Space>', 'Choose a tab with omnibar', function() {
    api.Front.openOmnibar({type: "Tabs"});
});
```

--------------------------------

### Map a key sequence in normal mode

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Use this to map a new keystroke to an existing one in normal mode. The domain parameter can restrict the mapping to specific websites.

```javascript
map(';d', '<Ctrl-Alt-d>');
```

--------------------------------

### Previous mapkey usage without api object

Source: https://github.com/brookhong/surfingkeys/wiki/Migrate-your-settings-from-0.9.74-to-1.0

This shows the older syntax used before version 1.0, where functions like `mapkey` did not require the `api` prefix.

```javascript
mapkey('<Ctrl-y>', 'Show me the money', function() {
    api.Front.showPopup('a well-known phrase uttered by characters in the 1996 film Jerry Maguire (Escape to close).');
});
```

--------------------------------

### Windows Registry File for Google Chrome

Source: https://github.com/brookhong/surfingkeys/blob/master/src/nvim/server/Readme.md

This .reg file adds the necessary registry key for Google Chrome to recognize the Surfingkeys native messaging host. Import this file to enable the integration.

```reg
Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\SOFTWARE\Google\Chrome\NativeMessagingHosts\surfingkeys]
@="C:\\Users\brook\.Surfingkeys_NativeMessagingHosts\surfingkeys.json"
```

--------------------------------

### Configure Lurking Pattern

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Specify pages where Surfingkeys should lurk by default. Only specific keys are registered in lurk mode.

```javascript
settings.lurkingPattern = /https:\/\/github\.com|.*confluence.*/i;
```

--------------------------------

### map

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Maps a key sequence to another in normal mode. This function allows users to define custom shortcuts.

```APIDOC
## map

Map a key sequence to another in normal mode.

### Parameters

* `new_keystroke` (string) - a key sequence to replace
* `old_keystroke` (string) - a key sequence to be replaced
* `domain` (regex) - a Javascript regex pattern to identify the domains that this mapping works. (optional, default `null`)
* `new_annotation` (string) - use it instead of the annotation from old_keystroke if provided. (optional, default `null`)

### Examples

```javascript
map(';d', '<Ctrl-Alt-d>');
```
```

--------------------------------

### Clipboard.write

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Writes specified text content to the system clipboard.

```APIDOC
## Clipboard.write

### Description
Writes specified text content to the system clipboard.

### Parameters
* `text` **[string]** the text to be written to clipboard.

### Request Example
```javascript
Clipboard.write(window.location.href);
```
```

--------------------------------

### CSS for Button Styling

Source: https://github.com/brookhong/surfingkeys/blob/master/tests/data/too-low-buttons-2294.html

Defines the appearance of buttons, setting their width, height, and background color.

```css
button { width: 100%; height: 8px; background-color: #000; }
```

--------------------------------

### Windows Registry File for Chromium

Source: https://github.com/brookhong/surfingkeys/blob/master/src/nvim/server/Readme.md

This .reg file adds the necessary registry key for Chromium to recognize the Surfingkeys native messaging host. Import this file to enable the integration.

```reg
Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\SOFTWARE\Chromium\NativeMessagingHosts\surfingkeys]
@="C:\\Users\brook\.Surfingkeys_NativeMessagingHosts\surfingkeys.json"
```

--------------------------------

### Search Selected Text on This Site with Google

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

Press `sog` to search selected text specifically within the current website using Google.

```Surfingkeys
sog
```

--------------------------------

### Map Key Sequence in ACE Editor

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Maps a key sequence to another in the ACE editor for a specified mode (e.g., 'normal', 'insert').

```javascript
aceVimMap('J', ':bn', 'normal');
```

--------------------------------

### Front.showPopup

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Displays a message in a popup window. Useful for temporary notifications or alerts.

```APIDOC
## Front.showPopup

### Description
Show message in popup.

### Parameters
* `msg` **[string]** - The message to be displayed in popup.

### Examples
```javascript
Front.showPopup(window.location.href);
```
```

--------------------------------

### Reload Markdown Source

Source: https://github.com/brookhong/surfingkeys/blob/master/README.md

On the markdown preview page, press r to reload the markdown source from the clipboard.

```vim
r
```

--------------------------------

### vunmap

Source: https://github.com/brookhong/surfingkeys/blob/master/docs/API.md

Unmaps a key sequence in visual mode. This is the visual mode equivalent of `unmap`.

```APIDOC
## vunmap

* **See**: unmap

Unmap a key sequence in visual mode.

### Parameters

* `keystroke` (string) - a key sequence to be removed.
* `domain` (regex) - a Javascript regex pattern to identify the domains that this mapping will be removed. (optional, default `null`)
```