More from "SearchLink Tips"

Continuing on from the previous SearchLink Basics post, this one will cover custom site searches and setting up a default configuration.

Custom searches

In brief, a custom search is simply a site-specific search performed using Google or DuckDuckGo with search parameters that include site:customsite.url. There are some other variations available, but that’s the essence of a custom search. You can access this type of search on the fly by just using a domain name instead of a search abbreviation in a search. For example, running the following search will search for searchlink on this site only:

!brettterpstra.com searchlink
=> [searchlink](https://brettterpstra.com/projects/searchlink/)

However, if there are site searches you use often, it would be worth having an abbreviation, right? That’s where a configuration file comes in.

As mentioned in the previous post, you can see a list of all available searches by selecting just the word help and running SearchLink. At the bottom of this list you’ll see a section called “Custom Searches.” This comes pre-populated with a selection of example searches, but you can add your own by editing a configuration file.

The first time you run SearchLink, it creates a hidden configuration file in your home directory called .searchlink. If you know your way around Terminal at all it should be easy enough to edit this file. If you’re not a command line person, you’ll want to do this from Finder:

  1. Open your user folder in Finder using Go->Home or just typing ⇧⌘H (Shift-Command-H)
  2. Show invisible files by typing ⇧⌘. (Shift-Command-Period)
  3. Locate .searchlink in the file listing (it will be visible but greyed out)
  4. Right click on .searchlink and choose Open In…
  5. Select TextEdit (or your preferred text editor)

The configuration file is fully commented (lines beginning with #), explaining what each option does, so I won’t go line-by-line here. Feel free to set your default options as desired. The format is YAML, which for the most part just means that the options are specified as a key and a value separated by a colon. The exception is arrays, which includes the custom_site_searches section. This consists of an indented list following the key. You can just edit and continue the existing examples, maintaining the formatting that’s already there.

A basic site search is just an abbreviation and a domain (no protocol, e.g. “http://”). If I have this in my configuration:

custom_site_searches:
  bt: brettterpstra.com

…then I can use !bt search terms as a search and it will run it as if it were a !g (default Google) search, but only return urls within the “brettterpstra.com” domain. That’s the whole deal with custom site searches.

The other type of custom search is substitutions. These are urls where your search term is inserted directly into the url and returned. These are specified by including the protocol (“http://” or “https://”) or beginning the value with a forward slash (/). Use $term to indicate where the search term is inserted. For example:

abbr: https://www.abbreviations.com/$term

This now allows me to use !abbr WTF (or [WTF](!abbr)) to create a link to an abbreviations.com search, i.e. https://www.abbreviations.com/WTF.

Using $term will insert an escaped version of the entire search string. You can also access each word of a search (space separated) and insert them using $term1, $term2, $term3, and so on. To make the inserted terms lowercase, just add a d suffix, e.g. $term2d.

Remember, you can see all of your available searches, including any custom abbreviations you define, using the help search. That way, if you go nuts defining a long list of searches, you’ll be able to recall them easily. I’m always looking out for the overzealous nerds, a.k.a. “kindred spirits.”

Flags and options

There are several “flags” available for searches. If you’re familiar with command line utilities, the formatting will be familiar. If not, don’t worry, I think it’s pretty intuitive.

Flags are options starting with a double hyphen, e.g. --validate_links. In its base state, a flag will always enable the specified option. You can negate the option by prefixing --no-, e.g. --no-validate_links. The available flags are:

  • --inline
  • --include_titles
  • --validate_links

These allow you to specify on a per-search basis whether the link format is inline (vs. title reference), whether the title of the link result is included in the output, and/or whether a validation check is run on the result to ensure it exists.

These flags can be specified in any search, e.g. !g search terms --include_titles or [search terms](!g --include_titles), or they can be included in a custom search definition in the configuration file. The latter is especially useful for the aforementioned substitution-type custom searches, allowing you to run verification on the resulting string to ensure that you’ve created a link that actually exists. For example, I have a custom search that lets me quickly link projects on my site, which follow the url format https://brettterpstra.com/project/[lower_case_project_name]. I can include validation on these links so that whenever I create one using the short syntax, it will ensure that I didn’t link to a 404:

btp: https://brettterpstra.com/project/$term1d --validate_links

This would create the url using the first search term, lower-cased, and then run a check to make sure the result actually exists. Inserting a misspelled project name would let me know I messed up, both with a notification (if enabled) and an HTML comment in the result:

!btp searchlinker <!-- Errors: (No results) (): Link not valid: http://brettterpstra.com/projects/searchlinker/ -->

If the link is inserted using the bracket syntax, the original markup is left alone and the HTML comment with errors is inserted at the end of the file/selected text. Conversely, if you have link validation enabled for all links but want to avoid it on a specific search, you can use --no-validate_links.

Option Abbreviations

The long flags can be abbreviated using single letters:

  • inline: i
  • include_titles: t
  • validate_links: v

Prefix the letter with ++ to enable the option, or -- to disable. Multiple options can be combined, and both positive and negative options can be included, e.g. !g markdown ++tv --v.

Per-Document Options

You can override configuration options for an entire document using MultiMarkdown metadata. This just means lines at the very beginning of a file consisting of key, colon, and value. These options are only read if they’re included in the selection you run SearchLink on, or if you run SearchLink on the entire file.

Options you can override are:

  • debug
  • country_code
  • inline
  • prefix_random
  • include_titles
  • validate_links

If I wanted every link in a document to be formatted inline and validated, I would include at the top of my file:

debug: true
inline: true
validate_links: true

Any of the options could also be set to false to negate them.

I’ll wrap this installment up here. Don’t worry, we’ve covered most of the features, it doesn’t get any more complicated from here, just more flexible and full-featured. Stay tuned!