Welcome to Dash's User Guide. The sections below will help you get the most out of Dash. As always, feel free to contact me about anything if you need further help.

Downloading Dash docsets is simple, just open Preferences > Downloads.

Xcode docsets can be downloaded from Xcode's Preferences > Downloads > Documentation. After the download finishes, open Dash's Preferences > Docsets and click the Rescan button at the bottom right. Dash will then find the new docsets that Xcode installed.

Please note that Xcode leaves around a lot of empty/corrupt docsets. If Dash shows duplicate docsets in Preferences > Docsets, you should right click each of them, choose "Show in Finder" and then manually delete them all. Afterwards, redownload the docsets using Xcode. This will ensure that you'll get rid of all the docsets left around by previous versions of Xcode and save some disk space.

Instructions on generating docsets can be found here.

You can manage the docsets you have installed from within Preferences > Docsets. You can drag and drop docsets to change the order in which results appear. If you're looking for more advanced ways of managing docsets and easier switching between them, see the sections below about Search Profiles and Docset Keywords.

If you're looking for a way to download/install docsets, see the Downloading docsets section.

You can set up collections of docsets and easily switch between them using search profiles. For example, let's say you do both OS X and Web development, you could set up a "OS X" search profile which automatically gets activated when Xcode launches and a "Web" search profile which automatically gets activated when Coda launches.

Search profiles persist between Dash launches and searches. If you explicitly do not need persistence, use docset keywords.

You can find the search profile settings by clicking on the loupe icon of the main search field:

Trigger types:

Search Keywords
Search keywords are typed inside of Dash's main search field and activate a profile. In the screenshot above, whenever the user types "web:" in the search field, the Web search profile is activated. Search keywords can also be used with the dash:// URL scheme, which makes it very easy to integrate them into plugins and extensions. For more details, see the dash:// custom URL scheme section.
App Activation
App Activation triggers activate a search profile whenever a given app becomes active. In the example in the screenshot above, whenever Coda becomes active, it also activates the "Web" search profile.
Global Keyboard Shortcut
Whenever you press a combination of keys in any app, the profile gets activated and Dash is shown.

Docset keywords are a very easy way to search a specific docset, regardless if it's enabled or not. Each docset has a default keyword which can be edited in Preferences > Docsets. Keywords are typed inside of the main search field.

For example, PHP's default keyword is "php:". Typing "php:printf" would search the PHP docset for "printf". Note: this assumes you have the PHP docset installed.

Docset keywords can also be used with the dash:// URL scheme, which makes it very easy to integrate them into plugins and extensions. For more details, see the dash:// custom URL scheme section.

You can assign the same keyword to more than one docset, and Dash will search them all. However, you might want to consider using Search Profiles instead which provide more flexibility for activating collections of docsets.

Docsets which support the "Table of Contents" feature show a filterable list of entries inside Dash's table of contents which is located at the bottom left of the Dash window (when shown). You can easily navigate this table using ALT+Down/Up arrow.

The screenshot below shows the table of contents in action:

Integration plugins for various 3rd party apps, as well as generic integration methods (e.g. AppleScript or Shell/Terminal scripts) can be found in Preferences > Integration.

All the integration plugins use the dash:// URL scheme behind the scenes, so it might be worth reading the help section for the dash:// custom URL scheme to gain understanding of search keywords and how to limit a plugin to search only a specific docset.

The global search shortcut is an easy way to activate Dash in a similar style as the Spotlight shortcut. You can assign a search shortcut in Preferences > General and then use that hotkey in any app when you want to bring up Dash.

You can assign more global search shortcuts using Search Profile activation triggers. Search Profiles can also automatically switch and enable different collections of docsets.

The "Look Up in Dash" system service can be used to initiate a Dash search using the currently selected text of any app.

Using the service from the contextual menu
Right click on some text in any app and choose Services > Look Up in Dash from the contextual menu.
Using the service with a global keyboard shortcut
You can assign a keyboard shortcut for this service in Preferences > General.
Warning! Some apps do not support OS X system services. Most notably, Java-based apps.

The dash:// custom URL scheme can be used to initiate a Dash search from any app that supports opening a custom URL.

  • The format is: dash://{query}. Example: dash://string.
  • You can also include an optional keyword: dash://{keyword}:{query}. Example: dash://php:printf (note: PHP docset must be installed).
    • Keywords can be used to specify which docsets exactly you wish to search. Keywords can be either docset keywords or Search Profile keyword triggers.

A more advanced dash-plugin:// custom URL scheme is available for plugin developers.

While viewing a documentation page or snippet, you can press CMD+F to initiate an in-page search.

However, please note that in-page search occurs in the same search field as the regular search. In a nutshell, anything that comes after a whitespace is searched in-page.

This is what the main search field looks like while searching for stringWithFormat inside the NSString documentation page:

Due to the "anything that comes after a whitespace is searched in-page" functionality, you might run into problems while trying to search for something that actually contains a whitespace (e.g. a Guide). To search entries that contain whitespaces, omit the whitespace. For example, if you'd like to find the String Programming Guide, you can search for StringProgramming or StringGuide or anything like that as long as you omit the whitespace.

Snippets are really simple pieces of text which you reuse often. The idea is to save a text/code snippet for later and expand it whenever you need to.

A snippet consists of:

Abbreviation
  • This is what you type in any app to expand snippets. The abbreviation gets replaced by the snippet body wherever you type it.
  • It is highly recommended that your snippet's abbreviation should contain a symbol, in order to avoid expansions by mistake. I personally use a backtick (`).
Body
  • This is the piece of text/code you'd like to save and reuse.
Variable Placeholders
  • Placeholders are the parts of the snippet that change on each expansion. For example, variable names could be placeholders.
  • Placeholders are defined by wrapping them in __ (double underscores). For example, __var__ is a placeholder.
  • Each time you expand a snippet, you are asked to fill in placeholders (if any).
  • Placeholders can change the case of the first letter (e.g. lowercase to uppercase). For example, __name__ and __Name__.
  • If __ does not suit your needs, you can define your own placeholder delimiter in Preferences > Snippets.
Special Placeholders
  • @clipboard - expands into the contents of the clipboard.
  • @cursor - repositions the cursor after expansion. Warning: this feature does not work very well with non-accessible apps.
  • @date - expands into the current date. You can modify the format in Preferences > Snippets.
  • @time - expands into the current time. You can modify the format in Preferences > Snippets.
  • You can escape (disable) these special placeholders by typing a \ before them.

The following screenshots show a snippet as defined in Dash and the same snippet while being expanded:

It is highly recommended that your snippet's abbreviation should contain a symbol, in order to avoid expansions by mistake. I personally use a backtick (`).

To create or edit a snippet start typing into the snippet editor. Snippets are automatically saved.

To manage snippets and show the snippet editor, click one of the highlighted buttons from the screenshot below:

You can search snippets by typing in the main search field. However, it might be hard to find the snippet you want if you have a lot of docsets enabled. To avoid this, you can create a snippets only Search Profile. For more information about search profiles, see the Search Profiles help section.
Dash can sync snippets between Macs if you save your snippet library into your Dropbox folder. You can change your snippets library location in Preferences > Snippets.

To disable snippet expansion, either delete the snippet or add a few symbols (e.g. whitespaces) at the end of the snippet's abbreviation.

In Mavericks, you can disable snippet expansion by disabling Dash's accessibility support. You can do this in System Preferences > Security & Privacy > Privacy > Accessibility > Disable Dash.

Dash is free on the Mac App Store - you purchase Dash using an In-App Purchase located in Preferences > Purchase. This is so that you can test Dash out before purchasing.

If you are sure you have previously purchased Dash using the In-App Purchase located in Preferences > Purchase, check out the Can't purchase or can't restore purchases help section.

Unfortunately, the App Store can act funny sometimes and get confused by its own caches. I have contacted Apple about it and they seem to have no interest in fixing this bug.

Check out the In-App Store Troubleshooting page for step-by-step instructions on how to attempt to fix this issue.

Xcode leaves around a lot of empty/corrupt docsets. If Dash shows duplicate docsets in Preferences > Docsets, you should right click each of them, choose "Show in Finder" and then manually delete them all. Afterwards, redownload the docsets using Xcode. This will ensure that you'll get rid of all the docsets left around by previous versions of Xcode and save some disk space.

There are 2 things that could prevent snippet expansion from working and in both cases Dash should have warned you about it:

1. Support for assistive devices is turned off. This needs to be turned on for snippet expansion to work. You can turn this on in System Preferences > Accessibility (the checkbox at the bottom), or in 10.9+ (Mavericks) from System Preferences > Security & Privacy > Privacy > Accessibility. If it was turned off, restart Dash after turning it on.

2. You have an app running that enables Secure Input but forgets to turn it off, you need to identify which app is causing this. Usually, web browsers or an extension inside web browsers is the culprit. To find where the problem is, quit the apps you have running one by one and try expanding after each one. If expansion starts working after you quit an app, that was the app that turned on Secure Input and forgot to turn it off.