• Download SearchLink

• Introduction
• Basic search format
• Advanced search format
• Available searches
• Examples
• Installation
• Usage
• Configuration
• Download
• Bonus for LaunchBar users

See the 2.1 release post for details on what’s new.

Introduction

SearchLink is a System Service for OS X (Mavericks compatible) 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 has replaced 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.

Basic search format

You can highlight any text and run SearchLink. By default, it will run a Google search and replace the text with a Markdown link to the first result. If you end the selected text with “!!”, it will only output the url. This form is good for quick searches from LaunchBar or Alfred. If you end the search with a “^” — which can be before or after a “!!” — it will copy the result to the clipboard and not print anything out.

To search Google for a link to MailMate and copy it to your clipboard, you just use:

mailmate app !!^

You can also run a basic search with one of the !args listed below. Start the selection or input with !(search type) and all of the text after it in the selection becomes the search terms for that type.

To run a “software” search for MailMate and output only a link:

!s mailmate!!

Running just !s mailmate will replace the selection with a full Markdown link.

These searches are designed for quick, on-the-fly searching.

You can also create a reference-format Markdown link by placing a colon (“:”) at the end of the query. That lets you write a query on a line by itself and turn it into a link you can use later while writing.

Advanced search format

When you’re writing or blogging, it’s time consuming to think about linking as you go. With these formats, you can basically leave a note about what a certain phrase should be linked to and keep writing. When you’re done, run SearchLink on the entire selection and all of your “noted” links will be updated.

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 2 app") produces [Marked 2 - smart tools for smart writers](http://marked2app.com/ "Marked 2 - smarter tools for smarter 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
  • !ipod : iTunes podcast 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)
• Twitter and ADN usernames
  • !@t : Link text as Twitter username
  • !@adn : Link text as App.net username

If no [](!xxx) syntax is found in the text you run SearchLink on, it will default to a Google search for the entire selected text, replicating the behavior of the previous “Auto-link web search” command in the Markdown Service Tools.

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")
* [ttscoff](!@t) and [ttscoff](!@adn)

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]
* [ttscoff][12] and [ttscoff][13]

[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"
[12]: https://twitter.com/ttscoff
[13]: https://alpha.app.net/ttscoff

(See the rendered output here)

You can also fill empty links using Google searches. If a search link doesn’t have text but has a search query, the page title of the result is used for the anchored text. If it doesn’t have a link but has text, the text is used for the query and the link is inserted.

* Default to Google: [brett terpstra]() 
    => [brett terpstra](http://brettterpstra.com/)
* Default to Google: []("brett terpstra") 
    => [Brett Terpstra](http://brettterpstra.com/)
* Default to Google, preserving link text: [me]("brett terpstra") 
    => [me](http://brettterpstra.com/)
* Macstories search for brett: [](!ms "brett terpstra")
    => [MacStories Interviews: Brett Terpstra - MacStories](http://www.macstories.net/stories/macstories-interviews-brett-terpstra/)
* TUAW search for brett: [](!tuaw "brett terpstra")
    => [Brett Terpstra - TUAW.com](http://www.tuaw.com/editor/brett-terpstra/)

When running it on a full document, you can rest assured that it won’t touch links that area already complete or that weren’t intended to be searches:

• Complete urls are preserved:
  • [Projects](http://brettterpstra.com/projects/cheaters)
  • [Cheaters](/projects/cheaters)
  • [Cheaters](projects/cheaters/index.html)
• Searches that return no results leave the original markup intact

It will ignore any malformed searches, too:

• Empty sets do nothing: []()
• Empty search text does nothing: [](!g)

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

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.

In order to avoid editing the Service directly (and having your configuration overwritten with every update), you can create a .searchlink file in your home directory. An example file with all configuration options and explanations can be found here. Download and save it as .searchlink in your home directory, and edit the configuration options described below in that file.

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 are left as is.

If you’re a LaunchBar or Alfred user, you can also use the Service directly on any input text, or create an Action to simplify searching from the launcher.

Configuration

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

In order to avoid editing the Service directly (and having your configuration overwritten with every update), you can create a .searchlink file in your home directory. An example file with all configuration options and explanations can be found here.

• 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 want iTunes searches to fall back to Google when they come up empty, set itunes_fallback to true.

• 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. (Set to [] or false to disable). The final config option should look something like:

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

• To set iTunes searches to use a specific country (default US), set the country_code variable to the two-letter abbreviation for the desired locale.

• You can create your own custom searches using the custom_site_searches key. This needs to be an array of key/value pairs, with the key being the shortcut and the value being the site to search. The formatting is standard YAML, and should look like this:

    custom_site_searches:
      bt: brettterpstra.com
      md: www.macdrifter.com
      tuaw: www.tuaw.com
      ms: macstories.net
      dd: www.leancrew.com
      sp: macsparky.com
      man: developer.apple.com
      dev: developer.apple.com
  

  Note that each line under custom_site_searches is indented by two spaces.

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.

Bonus for LaunchBar users

With the AppleScript below saved to ~/Library/Application Support/LaunchBar/Actions/Instant Search.scpt, you can use SearchLink as a launcher for the web. Load the action in LaunchBar, type Space and enter a SearchLink simple query (just text with optional !arg at the beginning). When you hit Enter it will grab the first link and load it in the Open URL action. Enter again will open it in your browser, ⌘C will copy it to your clipboard.

Note that you don’t need the normal “!!” at the end of the search string to specify that SearchLink should just return the URL, that’s included in the script.