Protocol Handlers

Integrate Zeal with IDEs and browsers using dash:// and dash-plugin:// URL schemes

Zeal supports custom URL schemes for deep linking and IDE integration, compatible with the Dash URL protocols.

Supported Protocols

Zeal implements two URL schemes:

dash://

Simple protocol for basic search queries

dash-plugin://

Advanced protocol with parameters for IDE integration

dash:// Protocol

The dash:// protocol provides a simple way to search documentation.

Syntax

dash://[query]

Examples

Basic Search

dash://string

URL Variations

Zeal accepts different URL formats:

dash://query
dash:query
dash:///query

All variations are treated identically after parsing.

dash-plugin:// Protocol

The dash-plugin:// protocol supports advanced parameters for IDE integration.

Syntax

dash-plugin://[?keys=<keywords>&query=<query>&prevent_activation=<bool>]

Parameters

keys · string

Comma-separated list of docset keywords to search

Example: keys=python,django

query · string

Search query string

Example: query=pprint

prevent_activation · boolean · default: "false"

Prevent Zeal window from being activated

When true, Zeal updates the search results but doesn’t bring the window to the foreground. Useful for background updates while coding.

Example: prevent_activation=true

Examples

Simple Query

dash-plugin://query=print

Using Protocol Handlers

From Command Line

You can invoke protocol handlers directly from the command line:

zeal "dash://python:pprint"

zeal "dash-plugin://keys=javascript&query=setTimeout"

From Web Browser

Create clickable links in HTML:

<a href="dash://python:print">Python print() documentation</a>

<a href="dash-plugin://keys=css&query=flexbox">CSS Flexbox Guide</a>

From Applications

Other applications can open Zeal URLs using system APIs:

Python

import webbrowser
webbrowser.open('dash://python:requests')

Windows Registration

On Windows, protocol handlers must be registered in the system registry.

Automatic Registration

Use Zeal’s built-in registration:

zeal.exe --register

This creates registry entries for both dash:// and dash-plugin:// protocols.

Manual Registration

The registration creates the following registry structure:

HKEY_CURRENT_USER\Software\Classes\dash
HKEY_CURRENT_USER\Software\Classes\dash-plugin

Each protocol is registered with:

• Default description
• URL Protocol marker
• Default icon
• Command for opening URLs

Unregistration

To remove protocol handlers:

zeal.exe --unregister

Protocol handlers are registered per-user (HKEY_CURRENT_USER), not system-wide.

IDE Integration

Many IDEs and text editors support Dash protocol integration.

Visual Studio Code

Install a Dash integration extension:

1. Search for “Dash” in the Extensions marketplace
2. Configure the extension to use Zeal
3. Set the executable path to Zeal

Sublime Text

Use the DashDoc plugin:

1. Install via Package Control
2. Configure for Zeal in settings:
   {
     "dash_app": "zeal"
   }
   

Vim/Neovim

Use a plugin like vim-dasht or dash.vim:

" Example configuration
nnoremap <silent> K :!zeal "<cword>" &<CR><CR>

Emacs

Use the zeal-at-point package:

(global-set-key (kbd "C-c d") 'zeal-at-point)

JetBrains IDEs

Install the Dash plugin from the marketplace and configure it to use Zeal.

Advanced Integration

Context-Aware Search

IDE plugins can detect the current programming language and automatically scope searches:

# Editing a Python file
dash-plugin://keys=python&query=<selected_text>

# Editing a JavaScript file
dash-plugin://keys=javascript,nodejs&query=<selected_text>

Background Updates

For non-intrusive documentation lookup, use prevent_activation=true:

dash-plugin://keys=rust&query=Vec&prevent_activation=true

This updates the search in Zeal without stealing focus from your editor.

Custom Keybindings

Bind a key in your IDE to open Zeal with the current selection:

VS Code

{
  "key": "ctrl+h",
  "command": "extension.dash.specific",
  "when": "editorTextFocus"
}

Sublime Text

{
  "keys": ["ctrl+h"],
  "command": "dash_doc"
}

URL Encoding

Special characters in queries should be URL-encoded:

# Searching for "std::vector"
dash://cpp:std%3A%3Avector

# Searching for "array[index]"
dash-plugin://query=array%5Bindex%5D

Zeal automatically decodes URL-encoded parameters.

Troubleshooting

Protocol not recognized (Windows)

Run Zeal with administrator privileges and execute:

zeal.exe --register

Verify the registry entries exist in HKEY_CURRENT_USER\Software\Classes\.

Browser doesn't open links

• Check that protocol handlers are registered
• Some browsers require explicit permission for custom protocols
• Try opening the URL from command line first

IDE integration not working

• Verify Zeal is in your system PATH
• Check IDE plugin configuration
• Test protocol handlers manually from command line
• Ensure Zeal is not already running in single-instance mode

Query not working as expected

• Check URL encoding for special characters
• Verify docset keywords match installed docsets
• Test the query directly in Zeal’s search box

Security Considerations

Protocol handlers execute local applications, which can pose security risks:

Be cautious when clicking protocol links from untrusted sources. Zeal itself doesn’t execute arbitrary code, but malicious URLs could attempt to exploit vulnerabilities.

• Zeal only accepts safe query parameters
• No file system access is granted through protocol URLs
• Commands are not executed; only search queries are processed

Examples

Quick Reference Links

Create a cheat sheet with quick links:

<!DOCTYPE html>
<html>
<head><title>Dev Quick Links</title></head>
<body>
  <h1>Documentation Quick Links</h1>
  <ul>
    <li><a href="dash://python:requests">Python Requests</a></li>
    <li><a href="dash://javascript:promise">JavaScript Promises</a></li>
    <li><a href="dash://css:grid">CSS Grid</a></li>
    <li><a href="dash://bash:awk">Bash AWK</a></li>
  </ul>
</body>
</html>

Shell Function

Create a shell function for quick lookups:

# Add to .bashrc or .zshrc
function zdoc() {
  local docset="$1"
  local query="$2"
  zeal "dash://${docset}:${query}" &
}

# Usage
zdoc python print
zdoc javascript array.map

Alfred/Raycast Integration

Create custom workflows to search Zeal:

# Alfred workflow script
zeal "dash-plugin://keys={query}&query={query}"

For best IDE integration, use dash-plugin:// with the prevent_activation parameter to keep focus on your editor while updating search results.