Web Search

Web searches open a search page in your browser from Raffi. Each one pairs a keyword with a URL template: type the keyword, a space and your query, press Enter, and Raffi opens the URL with your query filled in.

Quick start

addons:
  web_searches:
    - name: "Google"
      keyword: "g"
      url: "https://google.com/search?q={query}"
      icon: "google"

Type g rust traits. Raffi shows a row reading “Search Google for ‘rust traits’” and the resolved URL in the preview pane. Press Enter to open https://google.com/search?q=rust%20traits.

While you are still typing the keyword, a row naming the search appears; Enter or Tab on it jumps into the search. Esc closes Raffi.

URL encoding

The query replaces every {query} in the template and is percent-encoded first. Spaces become %20, other special characters are encoded (& becomes %26), and the unreserved characters A to Z, a to z, 0 to 9, -, ., _ and ~ stay as they are.

Simple query

g hello world
→ https://google.com/search?q=hello%20world

Special characters

g rust + traits
→ https://google.com/search?q=rust%20%2B%20traits

Quoted phrase

g "exact phrase" -exclude
→ https://google.com/search?q=%22exact%20phrase%22%20-exclude

Pre-configured Search Engines

Common search engines you can add:

General Search

- name: "Google"
  keyword: "g"
  url: "https://google.com/search?q={query}"
  icon: "google"

- name: "DuckDuckGo"
  keyword: "ddg"
  url: "https://duckduckgo.com/?q={query}"
  icon: "duckduckgo"

- name: "Bing"
  keyword: "b"
  url: "https://www.bing.com/search?q={query}"
  icon: "bing"

Development

- name: "GitHub"
  keyword: "gh"
  url: "https://github.com/search?q={query}"
  icon: "github"

- name: "Stack Overflow"
  keyword: "so"
  url: "https://stackoverflow.com/search?q={query}"
  icon: "stackoverflow"

- name: "Crates.io"
  keyword: "crate"
  url: "https://crates.io/search?q={query}"
  icon: "rust"

- name: "NPM"
  keyword: "npm"
  url: "https://www.npmjs.com/search?q={query}"
  icon: "npm"

- name: "Docker Hub"
  keyword: "docker"
  url: "https://hub.docker.com/search?q={query}"
  icon: "docker"

Reference

- name: "Wikipedia"
  keyword: "wiki"
  url: "https://en.wikipedia.org/wiki/Special:Search?search={query}"
  icon: "wikipedia"

- name: "MDN"
  keyword: "mdn"
  url: "https://developer.mozilla.org/en-US/search?q={query}"
  icon: "firefox"

- name: "Rust Docs"
  keyword: "rdoc"
  url: "https://doc.rust-lang.org/std/?search={query}"
  icon: "rust"

Media

- name: "YouTube"
  keyword: "yt"
  url: "https://www.youtube.com/results?search_query={query}"
  icon: "youtube"

- name: "Reddit"
  keyword: "r"
  url: "https://www.reddit.com/search?q={query}"
  icon: "reddit"

- name: "Twitter"
  keyword: "tw"
  url: "https://twitter.com/search?q={query}"
  icon: "twitter"

Shopping

- name: "Amazon"
  keyword: "amz"
  url: "https://www.amazon.com/s?k={query}"
  icon: "amazon"

- name: "eBay"
  keyword: "ebay"
  url: "https://www.ebay.com/sch/i.html?_nkw={query}"
  icon: "ebay"

Custom Search Engines

Any site that puts the search terms in its URL works. Search the site for test, copy the address from the browser, and replace test with {query}:

https://example.com/search?q=test
https://example.com/search?q={query}

The parameter does not have to be q, and {query} can sit anywhere in the URL, as in https://example.com/find?search={query}. Then add it to your config:

addons:
  web_searches:
    - name: "Example"
      keyword: "ex"
      url: "https://example.com/search?q={query}"

Examples

Site-Specific Search

- name: "Search Rust Reddit"
  keyword: "rr"
  url: "https://www.reddit.com/r/rust/search?q={query}&restrict_sr=1"
  icon: "reddit"

Google Images

- name: "Google Images"
  keyword: "img"
  url: "https://www.google.com/search?q={query}&tbm=isch"
  icon: "google"

Language-Specific

- name: "Python Docs"
  keyword: "pydoc"
  url: "https://docs.python.org/3/search.html?q={query}"
  icon: "python"

Fallbacks

Add a search to general.fallbacks as addons.web_searches."<name>" to offer it below the main list for any query, without typing its keyword.

Configuration

Web searches are a list under addons.web_searches (default: []).

name string (required)

Name shown in the search row, as in “Search Google for ‘rust traits’”.

keyword string (required)

Text that starts the search. Type it followed by a space: g enters the search, while g alone keeps searching the main list. Script filters, text snippet sources and the emoji and clipboard triggers are checked first, so they win over a web search with the same keyword.

url string (required)

URL template. Every {query} is replaced with the percent-encoded query, as described in URL encoding. A leading ~/ and ${VAR} references are expanded when the config loads, which lets you keep part of a URL, such as an internal host name, in an environment variable.

icon string

Icon name from your icon cache, shown next to the search row.

close_on_action boolean (default: true)

Close Raffi after opening the URL. When unset, general.close_on_action applies.

addons:
  web_searches:
    - name: "Google"
      keyword: "g"
      url: "https://google.com/search?q={query}"
      icon: "google"
    - name: "GitHub"
      keyword: "gh"
      url: "https://github.com/search?q={query}&type=repositories"
      icon: "github"
    - name: "Wikipedia"
      keyword: "wiki"
      url: "https://en.wikipedia.org/wiki/Special:Search?search={query}"
      icon: "wikipedia"
      close_on_action: false

Requirements

Raffi opens URLs with xdg-open, which uses your default browser.