Yub.js is an extensible client-side web command-line that comes with loads of useful search engines and shortcuts, reusable commands, and lots of other hidden goodies like stopwatches and inline YouTube videos. It also has a flexible API so you can call yub.js commands from anywhere: for example, you can link directly to commands, or access them right from your browser address bar (just set up a single search shortcut pointing at the yub.js API, and get hundreds of other search shortcuts for free).
The whole thing was designed from the outset to be a single page standalone html document containing everything needed to work out of the box. It can be installed locally and run right from your computer without the need for a server or web hosting. Since then it has grown considerably and development has been split into separate, more manageable files. The standalone html page version is still available, though it is now automatically generated by a ruby script, and comes in minified and source versions. Just save the page directly to your computer or drop it on your server and you're ready to go!
The list of available search engines is completely modular: you can drop in your own list of commonly visited websites by editing or replacing the mods.js file (json). Making your own new commands is easy -- just use the create
command (with the name of the new command as an optional argument). Feel free to add your own new functions or extend existing ones by editing functions.js
. Oh, and regular expressions are supported everywhere by default.
- 1 Cool Things To Try Out
- 2 Search Engines
- 3 Skins
- 4 Installation
- 5 API
- 6 Embedding
- 7 Upcoming Features
- 8 History
- 9 Development
- 10 It Might Not Be For You
- 11 Similar Projects
- 12 Acknowledgements
- 13 License
The best way to understand how yub.js works is to jump in and start trying commands. So before getting into boring things like history or internals, let's take a look at some of the cool commands you can try out right away.
- get a list of all available search shortcuts by typing
list
orls
- enter any full URL to go directly to the site, e.g.:
http://commandlinefu.com/
orftp://ftp.mozilla.org/
- add
!
in front of any bare URL to go directly to the site, e.g.: !smh.com.au to go to the Sydney Morning Herald - use
g [searchterm]
for a plain vanilla Google Search. Or you might prefer to usey
,b
,ix
, orsp
instead - help is available by typing
help
orman
(optionally including the command you want help with as an argument, e.g.help shuffle
)
calc 857*2^3
: solve simple mathematical formulascalc (25+2)==(28-1)
: test equivalencecalc ~32.56
: round numbersrand 550
: return a random number between 0-550rand site
: go to random websiterand img
: show a random imagerand git
: visit a random GitHub projectwatch ninja cat
: watch an embedded playlist of YouTube video results for the search term "ninja cat"link flint tigers
: get a permalink to the command flint tigers (which searches flickr for pictures of tigers sorted by "interestingness")fspell sometext
: write out sometext with flickr imagesascii sometext
: write out _sometext in ascii artwhere gn
: show the keyword and default search addresses for the command gn> am Alice in Wonderland
: go directly to the first Google search result for the term "Alice in Wonderland" on Amazon.com> wpde Turing complete
: read the article on "Turing completeness" in the German Wikipediacat engadget.com
: displays a text-only version of the webpage at engadget.compop bbc gn yn bn
: pop up individual tabs with BBC News , Google News, Yahoo News, and Bing News, all in one commandpop gim yim bim -t horses
: pop up new tabs showing results of an image search for horses on Google, Yahoo, and Bing
Note: to use the pop
command you will probably need to set up an exception in your browser's pop-up blocker for yub.js
Default search engines are stored in the engines.js file. This contains a wide variety of general-purpose web shortcuts, search engines, news sources and other interesting stuff that demonstrates the basic features of yub.js and should give you an idea of what kinds of shortcuts might be useful for your own needs.
Things you can expect to find in engines.js are: major search engines (Google, Yahoo, Bing... etc) and their various associated products (images, video, maps, news, weather, machine translation), Wikipedia and its various Wikimedia sister sites (Wiktionary, Wikiquote, Wikinews... etc), a selection of major news organizations (BBC, Deutsche Welle, France 24... etc), major webmail providers (Gmail, Yahoo, Hotmail... etc), documentation for several popular scripting languages (Bash, JS, PHP, Python, Ruby), and a bunch of other useful sites and tools (Down For Everyone Or Just Me?, Whois, What Is My Ip?... etc). A more detailed guide can be found in the wiki.
A nice benefit of using yub.js shortcuts is that https is used by default whenever possible (i.e. everywhere that it is supported).
All custom links and shortcuts go in mods.js for convenience. This file is entirely optional, so you can drop things in and out of it as you please. You do not need the mods.js file to use yub.js.
The gigantic mods.js file found in the repository is purely an example for the purposes of demonstrating various features of yub.js, such as unicode regex searches, as well as various local search sites and other interesting stuff that you can cherry-pick for your own uses. At 106 Kb / 870+ entries (as of this writing) it also demonstrates that even with a huge list of custom shortcuts, yub.js runs along smoothly without any noticeable decrease in speed.
Some examples of things that have been dumped indiscriminately in the sample mods.js file:
- International and local versions of the default websites in engines.js
- For example, all (as of this writing) international Google sites (including Google British Indian Ocean Territory and Google Pitcairn Islands...)
- Multilingual versions of most major international news aggregators and news websites (e.g. BBC, CNN, AFP, Deutsche Welle, Google News, etc)
- ฤll international eBay and Amazon sites (e.g.
ebin
for eBay India, oramuk
for Amazon U.K.) - Links to each of the language dictionaries at WordReference.com
- Note that each language pair has two separate links -- one for each direction. So, use
enes
for the English-Spanish dicitonary, andesen
for Spanish-English;enko
andkoen
for Korean,enfr
andfren
for French, etc.
- Note that each language pair has two separate links -- one for each direction. So, use
- A large (but not complete) selection of Wikimedia editions -- almost 30 major language versions of Wikipedia, Wikinews, Wikiquotes, Wiktionary, etc
- Complete multilingual collection of Global Voices links
- Complete multilingual collection of WikiHow links
- Most of the major Baidu, Sina, Sogou, Kvasir, and Yandex sites (search, images, maps, etc)
One thing to note is that some really interesting sites have been left out of engines.js and even mods.js in order to keep the default shortcuts as generally useful as possible. But never fear, you can still add them to your mods.js file! Here are some things you might consider adding to customize mods.js:
- Local classifieds: Both Cragslist and Kjiji have fairly straightforward search systems, but they don't offer sitewide search -- you have to choose your location first. Since it wouldn't make sense to prepackage any particular location (or shudder all of them), just create a
cl
orkj
command for your desired location and drop it in mods.js - Currency conversion: Create a shortcut to xe.com (or another site) with the following parameters:
http://www.xe.com/ucc/convert.cgi?Amount=%s&From=[CURRENCY1]&To=[CURRENCY2]
(replace[CURRENCY1]
and[CURRENCY2]
with the three-letter codes for the currencies of your choice)
- Local library catalogue: Create a shortcut to show search results from your local public or school library
- Blog search: Create a shortcut for search results on a blog you read often, or your personal website
- Local newspapers: The wiki will eventually host links to mods.js files for regional newspapers from around the world (so you'll be able to pick up a mods.js file for South African or Thai or Portuguese newspapers), but in the meantime create your own shortcuts to the local and international newspapers you read most frequently -- most websites have their own search function, but if not you can always link to a Google result for the specific site
- If your favourite radio station has an embeddable stream, you can add a link to it in functions.js and have it pop out under the command-line while you do other stuff
Theming support is available in the form of custom css files loaded through the skin
command. Skins are basically just css files (located in the /css
folder), and can be loaded by entering the command skin
and the name of the skin (there is no need to add the .css
extension).
To return to the default skin, just type skin default
. To remove all css, use skin none
.
Skins currently don't persist across yub sessions (this would require setting a cookie, which we've managed to avoid so far), but you can change the link/bookmark to your yub.js instance to something like https://dohliam.github.io/yub/?skin%20terminal
to always start yub.js with a particular skin loaded. Alternatively, once you decide on a skin you want to make the default for your local installation, just rename it to default.css
(you can rename the original default.css
file to old.css
or similar if you don't want to overwrite it). Your new file will be loaded as the default the next time you open up yub.js.
To make a new skin, just copy one of the existing skin files to a new file e.g. mynewskin.css
and customize to your heart's content! (And don't forget to add your custom skins to the skins gallery in the wiki so others can enjoy them!)
Here are some screenshots of the skins that come with yub.js:
default:
terminal:
mountainlake:
rays:
skyline:
nocss:
Of course you don't need to install yub.js in order to begin using it. For one-off searches you can easily use the latest version of yub.js hosted here on GitHub. Everything is done entirely on the client side, so none of your queries are sent over the network.
You can even use the API to make the GitHub version the default search for your browser. However, if you use the API any commands you enter will be visible (for example, in the GitHub server logs), so you might prefer to set up a local version of yub.js and run it entirely offline (or on your own site).
There is a detailed guide in the wiki on how to make yub.js your default search engine. You can find step-by-step instructions on how to set up yub.js for Chrome/Chromium and Firefox (if you use a different browser and are able to install yub.js, please consider adding the steps you took to the guide).
One thing to consider when installing yub.js whether you'd like to set it up as a keyword search or use it as your default search engine. The benefit of setting it up as your default is that it basically makes your browser's URL bar itself into a web command-line.
One of the most useful features of yub.js is its easy-to-use API, which works just as well on a laptop as it does on a server. Just point a link, bookmark, or keyword search at your yub.js URL and add ?
plus your commands or search terms to go directly to the result.
Example 1:
- yub.js URL:
http://example.com/yub
- command: weather tokyo
- full URL for this command:
http://example.com/yub?weather tokyo
Example 2:
- yub.js URL: file:///home/username/yub/index.html
- command: rand site
- full URL for this command:
file:///home/user/yub/index.html?rand site
You can embed yub.js on any webpage and get a functional web command-line that looks like this:
Just copy the following code and include it anywhere on the page:
<form method="get" action="#" onsubmit="window.location='https://dohliam.github.io/yub/?'+window.yub.value; return false"><img src="yub.gif" /> <input id="yub" type="text" size=27 value="yub.js web command-line" autocomplete="off" style="border-style: none none solid; color:gray; font-family:monospace;" onfocus="this.value=''; this.style.color='black'" onblur="if (this.value=='') {this.value='yub.js: enter commands here';this.style.color='gray'}"> <input style="visibility: hidden" type="submit" value="" />
There is probably a more elegant way to do this, but after some testing this seemed to be the only way that works in both Firefox and Chrome. Feel free to experiment and open a pull request if you find something better!
There are tons of features that have yet to be implemented. As much as possible, planned new functionality and requested features are being tracked in the issue tracker. If you have an idea, go ahead and add it in (or fork the project and shoot over a pull request)!
It would be awesome to see everyone's custom mods.js files -- links to these can be shared in the wiki, though a separate repository is another possibility in the future if the list gets big enough. In the meantime, let me know if you have a mods.js file you'd like to share -- particularly if it's organized around a specific theme (e.g., collections of social media sites, Swedish newspapers, research databases, tools for historians or marine biologists... etc).
Some planned features that are still in the works:
theming support (skins)done!- translation support for multiple languages
- command tagging
- more extensive man entries
- jukebox feature (like
watch
, but for music) - pipes!
If you'd like to contribute to adding any of these features (or others I haven't thought of), feel free to submit a pull request.
A long time ago (2005 to be exact), a groundbreaking website called YubNub was unveiled that allowed users to write their own commands and shortcuts for various web services. The idea of accessing websites with short bash-like commands was quite compelling and actually addictive, and quickly led to all sorts of creative tools like split and gimyim. Along with many others, I created a bunch of commands and used the site quite heavily for a while.
However, there was one thing that never quite made sense -- why would anyone want to filter every single search they did through a(nother) third party website? In any case, as soon Firefox's keyword search functionality became widely known, the allure of using YubNub shortcuts began to fade -- it was easier to just set up local Firefox keywords for most common searches and then use those instead. So a bookmark file containing dozens of former YubNub commands in the form of search keywords traveled from computer to computer, surviving for almost a decade before it became obvious that this system, too, was entirely too clunky, slow and impractical (e.g., access from another computer was a pain, and keeping the list updated across computers was also not pleasant). What was worse, this method also missed much of the exciting non-search command functionality that YubNub offered.
Nine years later, a visit to YubNub revealed that the service is still running, and according to Wikipedia, even boasted over 22,000 user-contributed commands... as of 2008. Looking at the list of commands leads one to the disheartening conclusion that the once awesome service has become swamped by thousands and thousands of spam entries, stifling any remaining sense of community (the social command-line) that was once one of the most endearing things about the site.
Even more disappointing, many of the coolest commands (e.g., split, gimyim) are no longer even functional. Of course, this should not really be all that surprising -- the architecture of the web has changed a lot since 2005. (In the case of split, both because loading websites in frames has stopped being a normal and acceptable thing to do, and also, as demonstrated by gimyim, because both Google and Yahoo -- as well as virtually every other major website -- now actively discourage attempts to load their content from external sites). Bummer.
Yub.js started out as an attempt to get back some of the functionality of the old YubNub command-line in an entirely client-side application that anyone could tweak or adjust to suit their needs and then run on their local machine -- or drop into the cloud or onto a private server and access from anywhere.
Although I had been kicking this idea around idly for years, it always remained something of a pipe dream, since I wasn't even sure if it was possible to do most of the stuff I wanted to do with JavaScript. Eventually I whipped up a little html page to redirect queries to a few common search engines and "yubSearch" was born.
However, it soon became clear that search shortcuts alone were not enough. A simple command to search through the shortcuts list was followed by other commands to print the date and time, show descriptions for each shortcut, and sort text. A calculator was added, and then a stopwatch. As new commands evolved out of bits and snippets of code and workarounds from all over the place, it became almost a challenge to see what could be cobbled together with pure JavaScript alone. It was no longer just about search shortcuts -- and thus yubSearch became yub.js.
Development has proceeded on a strictly itch-scratching basis, with new functionality being added when and as actually needed. From very early on, yub.js became something of its own development environment, and there are built-in reference tools for JavaScript (as well as other popular scripting languages), linters and an internal command creation syntax that have helped to make common development-related tasks much easier.
At some point, yub.js took on a life of its own. While not exactly Turing complete, it became dangerously close when a patch was contemplated to add Eliza as an engine to respond to conversational prompts...
Yub.js continues to be developed in pure JS without the use of frameworks or external libraries. Although many interesting functions could be added using server-side scripting, frameworks, and other bits of whiz-bang heavy coding artillery, the main goals have always been portability and responsiveness -- you can drop yub.js virtually anywhere: a desktop, a server, a ChromeBook, even a mobile phone, and it will work pretty much exactly the same way. This has proven to be a particular lifesaver on mobile devices where even simple searches (let alone anything more sophisticated) can sometimes be incredibly clumsy and frustrating to work with -- and when mobile websites often hide or dumb down basic features like search.
As mentioned above, however, the code has been literally cobbled together out of spare parts without (until very recently) any thought to making it look pretty, let alone standardized or efficient. Nevertheless, everything chugs along at an incredible speed, thanks to relatively small file sizes and the benefits of running entirely on the client side.
Could it be even faster? Absolutely! A lot of work no doubt remains to be done optimizing and prettifying the existing (admittedly quite ugly) codebase. Will the average user notice these improvements? That's harder to say -- after all, the difference between instantaneous response times and those that are half that speed can be pretty hard to discern. Most of the individual tasks that JavaScript is handling at any given time are incredibly trivial (making lists, redirecting to URLs), so speed has rarely if ever been a concern during actual use.
On the other hand, if things that are slower than they need to be bother you on principle, you may want to take a look at the next section.
-
Cloud sync afficionados: If you are still wondering what the point of all this is when you could just use Firefox Sync or sign in to Chrome with your Google Account, then yub.js may not be for you.
-
Bookmarks managers: Cloud sync options for almost all major browsers are now ubiquitous, and if not one of those services, you could always backup your bookmarks file on a server somewhere and be done with it. If that works for you, great -- but frustration with these approaches is what led to yub.js in the first place.
-
Sticklers for elegant code: As mentioned before, the code is pretty ugly at the moment -- not on purpose, of course, but since every new feature has been added due to some immediately pressing need, kludges and all sorts of brute force inefficient loops abound. That will hopefully change over time as the code is (slowly) refactored. But if ugly code offends you, you may want to avert your eyes.
-
Haters of eval: If you believe that eval is evil under any circumstances (even parsing sanitized mathematical expressions)... then you may want to just remove the calculator function from your version of yub.js.
-
Seekers of bash.js: Yub.js is not a port of bash into JavaScript. If you are wondering why yub.js doesn't offer a
mount
command, or have a way tokill
processes, ormodprobe
your mouse driver... you are probably in the wrong place (perhaps you are looking for unixkcd). On the other hand, if you can think of an appropriate metaphor formount
,kill
, ormodprobe
that would make sense on a web command-line, I'd love to hear from you! ๐
- YubNub (The original inspiration for yub.js)
- Inky (Firefox extension)
- Ubiquity (Firefox extension)
- unixkcd) (A commandline for the comic xkcd)
- JSShell (An actual UNIX-style shell written in JavaScript for the browser)
Many thanks to Jon Aquino, and everyone who contributed to YubNub in its heyday, for the web-as-command-line metaphor that was the original inspiration for yub.js.
Minified single-page version made using Uglifier for Ruby.
Table of contents generated by https://github.com/dohliam/tocdown.
The random GitHub repo is based on RandomRepo by RyanDavison.
Background wallpapers for various skins:
- "Untitled" by tiltti, released under a CC-BY license (used in the "mountainlake" skin)
- Mountain Monastery Sunrise by Ronan Shenhav, released under a CC-BY license (used in the "rays" skin)
- Hong Kong from Victoria Peak by Robert Lowe, released under a CC-BY license (used in the "skyline" skin)
MIT -- see LICENSE file for details.