diff --git a/src/vs/platform/opener/electron-browser/openerService.ts b/src/vs/platform/opener/electron-browser/openerService.ts
index 8f60eef8653bc385f6458bfbb4eec97cfbb9fa3f..667636f2db47c7601675b1fc22c132151fec71e1 100644
--- a/src/vs/platform/opener/electron-browser/openerService.ts
+++ b/src/vs/platform/opener/electron-browser/openerService.ts
@@ -5,6 +5,7 @@
 'use strict';
 
 import URI from 'vs/base/common/uri';
+import {parse} from 'vs/base/common/marshalling';
 import {Schemas} from 'vs/base/common/network';
 import {TPromise} from 'vs/base/common/winjs.base';
 import {IEditorService} from 'vs/platform/editor/common/editor';
@@ -34,7 +35,7 @@ export class OpenerService implements IOpenerService {
 			// execute as command
 			let args: any;
 			try {
-				args = JSON.parse(query);
+				args = parse(query);
 			} catch (e) {
 				//
 			}
diff --git a/src/vs/workbench/api/node/extHostApiCommands.ts b/src/vs/workbench/api/node/extHostApiCommands.ts
index e64a0836a7c2cf6a0f6db2f5c68208a8674c3aac..c56ddbb37338d373b0665ab91824be4ec4667328 100644
--- a/src/vs/workbench/api/node/extHostApiCommands.ts
+++ b/src/vs/workbench/api/node/extHostApiCommands.ts
@@ -159,8 +159,15 @@ class ExtHostApiCommands {
 				description: `
 					Render the html of the resource in an editor view.
 
-					Links contained in the document will be handled by VS Code whereby it supports file-resources and virtual resources
-					as well as triggering commands using the 'command'-scheme.
+					Links contained in the document will be handled by VS Code whereby it supports \`file\`-resources and
+					[virtual](https://github.com/Microsoft/vscode/blob/master/src/vs/vscode.d.ts#L3295)-resources
+					as well as triggering commands using the \`command\`-scheme. Use the query part of a command-uri to pass along JSON-encoded
+					arguments - note that URL-encoding must be applied. The snippet below defines a command-link that calls the _previewHtml_
+					command and passes along an uri:
+					\`\`\`
+					let href = encodeURI('command:vscode.previewHtml?' + JSON.stringify(someUri));
+					let html = '<a href="' + href + '">Show Resource...</a>.';
+					\`\`\`
 				`,
 			args: [
 				{ name: 'uri', description: 'Uri of the resource to preview.', constraint: value => value instanceof URI || typeof value === 'string' },