Find (I4kFind) is a privacy friendly, client side, local/URL first
toolkit, to customize a web browser's URL Omnibox (the search/address
bar).
There are more examples of usages, and development notes in the ./docs folder.
Remember, this is an experimental project, please make regular backups of your custom syntax, and "pin a package version that works" if you are running a custom instance. For full privacy, run a personal instance.
It does not need to be installed as a browser extension or addon, though the UX feels more fluid when used as "default search engine" (can be self hosted, but does not need to in order to be customized).
It does not make any search request itself, "just builds URLs" of specialized websites, to which is passed the user's "search query" (it could also be the value of URL parameters of any destination application).
On internet4000.github.io/find
it is possible to make queries to Find, such as !docs usage which
will redirect the browser page, to this document (to the link with
#usage).
How it could be used:
- as fallback when the browser does resolve a URL address
- "normal web search" by default (and if no Find syntax is found), to the "default web search engine"
- decide with which sites and application to share a search query, by "routing them" directly to a destination site
- choose on which search engine to search, web search (default), map
position (
!m), contacts (!c), wikipedia (!w) new spreadhseet (+sheet), matrix link&mx @user:domain.tld, create a WebRTCPeer data channel to&rtcmx @user:domain.tld) etc. It is all built on open standard web technologies - DuckDuckGo also supports Bangs!, which will then be used if Find
does not know a "search
!engine"; ex:!def find(will will delegate the to DDG, which knows what to do with!def) - save "user defined URLs" as engine(s) (a sort of "bookmark"), to be
re-accessed from their "shortcode",
!ex→https://example.org - "route" the user query (with arguments), to any website (application), by building its URL
- build (custom) "destination URL" from patterns and placeholders
https://example.org/my-app/{}/?query={}(no support for named placeholders yet) - URL utilility, build URIs, "data URL" (ex:
data:text/html,<h1>Hello world</h1>), to copy/share/edit/store temporary data, in various formats - "pipe" outputs of other web-apps together, by their "(URL) outputs"
- re-assign and customize the syntax, engines URLs and actions (under the exisiting symbols); so it is the "user's favorite applications/sites" that are used by default
- synchronize between device(s) and browsers, without additional user account (export/import to JSON, save as "site credentials", in JSON, and optionally synchronize with the user/browser's password manager)
- host a custom instance (with CI/CD or drag and drop), implemented in vanilla HTML/CSS/Javascript(web-components), with no dependency and no build-system (could be implemented with wasm or other tools)
- define a new custom/local/browser-based "open search" engine
- "locally self hosted", with the web interface (
git clone,npm i && npm run serve, openhttps://localhost?q=%s, should be discoverable as browser "open search engine"; and could use a different "suggestion API"; or under VPN, such as a Tailscale tailnet, for all devices to share) - (experiemental) get typing suggestions from a client side API
(web-worker following the OpenSearchDescription suggestion
specification, catching "fetch queries" made to its own domain
(
window.location/api/suggestions/)) - (experiemental) "proxy/polyfill URISchemeProtocol
<protocol><:><//><ressource>, to support a fallback when user requestsgopher://gopher.floodgap.com,gemini://kennedy.gemi.dev,finger://,text://etc. - as an accessible starting template to experiment with what can the browser URL can be used for, and how to interpret and execute queries, manage user defined data, syntax, functions
- an open "finder/Alfred/CLI" for the web; can be used to suggest
custom prefilled links and utilities (ex: community projects
+issueor+chat) - embeded in an other app/site (ex: matrix.org iframe widget)
- test/explore/save other aplication(s) "URL params", connect them together, transform their output(s)
- explore new URI schemes and string data de/encoding patterns
- customize a user browser's starting page, default new tab, homepage, HTML input and text string encoding/decoding/evaluation
For additional usages see the documentation folder.
Find is opened by the browser, as a search engine, with the query
typed by the user in their web-browser's URL bar (or from a query
inside a <i4k-find-search/> web-component, or a call to
Find.find("my query") etc.).
From the query, it will try to look for "the pattern it knows", to see it the user typed a Find query, if there are none, it will default to seaching, like a usual web-search, to the user's default search engine (to be defined by the user)
For community chat and support, see the #i4k-find:matrix.org room, or the git issues, as you see fit. Feedback, bug reports, engine/symbol/feature requests, suggestions welcome.
For new URL patterns, syntax and engine suggestions >i4kfpm <queyr>
for searching github repo with topics:
"i4k-find+package
It is possible to use Find with
- the default find instance website
- a personal find instance website (can customize more)
In general, the UX should feel nicer when any instance is defined as the default web browser's search engine. Otherwise it is also possible to use a browser search engine keyword (still need to install a Find instance as a search engine in the browser, but no need to defined as the default one, as long as it has a keyword, which has to be prefixed to every find query).
- use the npm package i4k-find.
- check the
./index.htmlfile for how to import the package and the GUI. - customize the
assets/opensearch.xmlfile for the new instance URL and information
It should be also available through a CDN: !cdn i4k-find to import.
The URL bar of web-browsers is used to write text, websites adresses and search queries. Find is a tool that offers a user the possibility to customize the functionalities of any (device) web-browser's URL Address Bar (aka the omnibox).
It is similar (and a lighweight, self-hostable, customizable, free software alternatieve) to DuckDuckGo bangs, and runs only in the user browser.
The code is javascript running client side, and can be customized with new search engines, synchronised across devices using the native browser's password manager (treating the user search engines custom configuration as a passwrod for the instance of find you're using).
It aims to be a lightweight way to enhance the URL bar, the URI building user-experience, accesible to use and install on personal instance(s).
It is Free software that can be customized and hosted quickly at your convenience.
The fastest way to try its features, is by testing it with the example queries on this page: try Find! here.
If you want to have the best experience, try it as your web browser's
default search engine; so all the features are accesible directly in
your URL bar (tip: focus the omnibox with the keyboard shortcut
Control + l, the keys Control and the lowercase letter L, aka
C-l ).
By default, a Find search query, goes to the default search engine
(!d) in our case, duckduckgo, and it is
possible to re-assign the "default search engine's value".
Here are example usage of user queries, one can type in an input
supporting Find queries (such as the one on the
homepage). A Find search input
will try to suggest the available symbols (!&+#) and their
associated engines.
In the examples, lines prefixed with
;;are comments, with;;→outputs URL or Find queries.
Example search with ! symbol:
;; "default search", without anything "Find related"
Hello world
;;→ https://duckduckgo.com/?q=hello+world
;; A "map" search, defaults to google map (can be re-assigned to open street map etc.)
!m egypt
;;→ https://www.google.com/maps/search/egyptExample build with & symbol:
;; go to, or buid a github profile/actor url
&gh
;;→ https://github.com
&gh internet4000
;;→ https://github.com/internet4000
&gh internet4000 find
... and more (all customizable)
;; to build a "matrix link to room/user" URL
&mx #i4k-find:matrix.org
;;→ https://matrix.to/#/%23i4k-find%3Amatrix.org
Example do with + symbol:
Type any of these in a Find search input, or in your browser URL bar (if Find is one of your browser search engine).
;; create a new google spreadsheet (with a title)
+sheet my new sheet
;; draw a new "google draw"
+draw hello world
;; take a note
+note My note content
;; create temporary "URL space" with text/|data
+space my data
;; create a "data json url" value
;; can be copied again to a new URL, stored as bookmark etc.
+data-json {"my-json": true}
Example command with the # symbol prefix (functions cannot
currently be user defined, only the other exisiting symbols):
;; to "save" an engine as a new "user defined engine" (userEngines)
#add ! ex https://example.org/
;;→ will save this URL, can be called as !ex
;; to add a new engine, with URL placeholders
#add ! ex https://example.org/blog/{}
;;→ will save this URL, can be called as !ex <blog-article-id>
;; to add a new "buid" engine, with URL placeholders
#add & ghi https://github.com/internet4000/{}
;;→ will save this URL, can be called as &ghi find (to reach the project)Some reasons why this project exists:
- gain (self) control of where search queries go after leaving the web-browser.
- to reflect on where all browser search queries and actions go (and their ammount)
- experiement with what can be done from typing into any browser's URL (is the current cursor in a URL bar, a text search input, a REPL, a notebook? Or it is just me typing on the keyboard?)
- experiment with maybe storing URL as bookmarks more easily; "local
first/only" database explorations of "my own content" (could also
optin keep track of searches, to re-use and edit, as
.bash_historyetc.) - try to handle "not just search" (alternative URL client entry point to DDG or Searx)
- explore using the different URI/URL(s) outputed by the "user/Find search queries", by the output(s) of the "web-app/sites" they serve, and what the user is intending to do
- share practical and nice URL(s) (
+wrand+wrifor serendipity, placeholders) - interacting with computing interface(s) (url, shell, repl, notes, chats, links) and other actors
Some reasons why DuckDuckGo is the default search engine:
- it supports
!bangs (13,563+ bangs! search engines) - it seems more privacy friendly that the rest (that support bangs; are there any other?)
- SearX instances have bangs suppport; maybe users can decide for themselves which one to use. (ref: issue#96)
Cons for DDG:
- seems to "re-writte" the search results when you visit the search result page, again, after visiting a first result's page
The code of this software uses the GNU General Public License
v3, which makes it Free
software (see
/license.txt).
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent