BrettTerpstra.com

SearchLink is a System Service for OS X that handles searching multiple sources and automatically generating Markdown links for text. It allows you to just write, marking things to link as you go. When you’re done, you run it on the document and — if your queries were good — have your links generated automatically without ever opening a browser.

This is similar to the “Auto-link web search” service in the Markdown Service Tools. The difference is that you can now mark links and specify how they should be searched for, as well as provide alternate query terms for linked text.

You format text to be linked with a familiar Markdown pattern:

[text to link](!arg "optional search text")

We’ll get into !arg in a second. The [text to link] portion is just that: the text that will be visible and linked in the output. "optional search text", if it exists, will be used as the search query instead of the link text. You can also leave the “text to link” portion empty and the title of the search result found with the “optional search text” will be inserted, e.g. [](!g "Marked app") produces [Marked - smart tools for smart writers](http://markedapp.com/ "Marked - smart tools for smart writers").

Available searches

SearchLink uses various API’s to provide results for specific types of queries. These are denoted by an exclamation mark followed by one of the following keys:

!arguments:

• Software
  • !mas : search Mac App Store
  • !masd : search Mac App Store, return seller URL
  • !itu : search iTunes App Store
  • !itud : search iTunes App Store, return seller URL
  • !s : software search using Google
• General
  • !g : first Google result
• Terminology
  • !wiki : Wikipedia link (Wikipedia API)
  • !def : Dictionary link/fallback to Wikipedia (DDG API)
• Music
  • !isong : iTunes song link
  • !iart : iTunes artist link
  • !ialb : iTunes album link
  • !lsong : Last.fm song link
  • !lart : Last.fm artist link
• Amazon
  • !a : Amazon product search in all categories
• Site search
  • any !address recognized as a url (no protocol required) will become a site-specific Google search for the link text (or specified search terms). e.g. [MarkdownEditing](!github.com)

The list may grow as I need it to, but it covers my bases for now.

Examples

Here’s a list of sample links.

* A search for specified text: [Marked](!g "Marked mac app").
* A simple software search for [Fantastical](!s).
* A simple google search [neat neat neat](!g)
* A Last.fm track search [neat neat neat](!lsong "The Damned Neat Neat Neat") (with specified search terms)
* Mac app store search: [Marked on the MAS](!mas "Marked")
* Mac App Store search [Marked direct](!masd "Marked") with direct dev site link.
* iTunes app search: [Boost 2](!itu) 
* iTunes search, direct dev site link: [Boost direct](!itud "Boost 2")
* This search: [](!mas "Purple animator") will have its link text filled in with the title of the first result.
* This is a wikipedia entry for [Sid Vicious](!wiki)
* This will put the definition of [ambiguous](!def) in the title field of a link to the dictionary entry.
* iTunes Artist search: [BRMC](!iart "Black Rebel Motorcycle Club")
* Site specific search: [Keybindings](!brettterpstra.com "Keybinding Madness")

When SearchLink is run on the above block of text, it outputs:

* A search for specified text: [Marked][1].
* A simple software search for [Fantastical][2].
* A simple google search [neat neat neat][3]
* A Last.fm track search [neat neat neat][4] (with specified search terms)
* Mac app store search: [Marked on the MAS][5]
* Mac App Store search [Marked direct][1] with direct dev site link.
* iTunes app search: [Boost 2][6] 
* iTunes search, direct dev site link: [Boost direct][6]
* This search: [Purple][7] will have its link text filled in with the title of the first result.
* This is a wikipedia entry for [Sid Vicious][8]
* This will put the definition of [ambiguous][9] in the title field of a link to the dictionary entry.
* iTunes Artist search: [BRMC][10]
* Site specific search: [Keybindings][11]


[1]: http://markedapp.com/ "Marked - smart tools for smart writers"
[2]: http://flexibits.com/ "Flexibits | Fantastical | Meet your Mac's new calendar."
[3]: http://www.youtube.com/watch?v=4JeDxJkAorU "The Damned Neat Neat Neat - YouTube"
[4]: http://www.last.fm/music/The+Damned/_/Neat+Neat+Neat "Neat Neat Neat by The Damned"
[5]: https://itunes.apple.com/us/app/marked/id448925439?mt=12&uo=4&partnerId=30&siteID=vRL5rYo4h5A "Marked"
[6]: https://itunes.apple.com/us/app/boost-2/id333191476?mt=8&uo=4&partnerId=30&siteID=vRL5rYo4h5A "Boost 2"
[7]: https://itunes.apple.com/us/app/purple/id433132196?mt=12&uo=4&partnerId=30&siteID=vRL5rYo4h5A "Purple"
[8]: http://en.wikipedia.org/wiki/Sid_Vicious "Sid Vicious"
[9]: http://dictionary.reference.com/browse/ambiguous "open to or having several possible meanings or interpretations; equivocal: an   ambiguous answer. 2. Linguistics. (of an expression) exhibiting constructional ..."
[10]: https://itunes.apple.com/us/artist/black-rebel-motorcycle-club/id624658?uo=4 "Black Rebel Motorcycle Club"
[11]: http://brettterpstra.com/keybinding-madness/ "KeyBinding madness - Brett Terpstra"

(See the rendered output here)

Note that it uses reference style linking by default. Duplicate results are culled and their marker repeated as needed, and it will begin numbering after the highest numbered reference located in the passed text. If you run it with only one (!arg) link in the selection, it will automatically switch to inline linking. See the configuration below if you want to always force inline linking.

Installation

Dependency: this whole system relies on JSON responses, and Ruby needs the json gem to run this. From the Terminal, run sudo gem install json and in most cases you’ll be good to go. If you’re running a Ruby environment manager (rvm, rbenv) make sure you’re installing the gem in the system Ruby. The service will always use /usr/bin/ruby.

Note: to install ruby gems you need to have the Xcode Command Line tools installed.

Download the zip file at the end of this post and double click it to extract the .workflow file. Place that file in HOME/Library/Services (or just double click it and it will ask if you’d like to install it). It should become available immediately.

You can assign a keyboard shortcut as well. See the howto for more information.

Usage

Select some text containing [link](!arg) format text, right/control click on the selection and find the “Services” menu at the bottom of the contextual menu that pops up (also available under the application menu in the menu bar). Under Services, select SearchLink and run it. It may take a while depending on how many links are in the text. Any links that return errors or no results will be left as is.

Configuration

There’s not a lot of configuration necessary. To see the available options, open the Service in Automator by double-clicking it.

• If you prefer to always use inline links, set inline to true.
• If you prefer not to have links prefixed with a random number (to avoid naming conflicts), set prefix_random to false.

• If you have an affiliate link set up with iTunes, enter the extra portion of the link in the itunes_affiliate variable. If you don’t have one or don’t want to use it, leave that variable set to empty quotes. The final config option should look like:

    itunes_affiliate = "&partnerId=30&siteID=vRL5rYo4h5A"
  

• If you are an Amazon Affiliate partner, set amazon_partner to an array containing your partner tag, your “camp” and “creative” ids. If you create a link to a product using the Amazon link tool, you can examine the url to find these sections easily. The final config option should look something like:

    amazon_partner = ["bretttercom-20","1789","390957"]
  

All donations are greatly appreciated!

Download

There will likely be updates to this as I solve more problems, so keep an eye on this page for new versions. The current source code is available as a gist.