URL Handler

Marked’s URL handler provides additional scripting and workflow capabilities. You can include a url in the notes of another application, for example, that will open a file in Marked when clicked. You can perform several actions, as listed below.

Optional parameters

x-success

Any command can provide an x-success query parameter. Set this to a url to be called after performing the command. For example: x-marked://open/?file=filename.md&x-success=ithoughts:. You can also provide a bundle identifier (such as com.googlecode.iterm) to open an application that doesn’t have a URL scheme.

raise

A raise parameter can be passed with any command that accepts a file parameter or affects all windows. After the action is performed, the window will raise above all windows (all applications) before returning or executing a callback.

"x-marked://refresh?file=filename.md&raise=true"

Calling from the command line/scripts

Calling the url handler from the command line or a script can be done using the macOS open command:

open 'x-marked://open?file=filename.md'
open 'x-marked://refresh?file=filename.md'

Calling in the background

You can call the open command with the -g flag to perform the result in the background without switching focus. To perform the command in the background and raise the window to the top without stealing focus:

open -g 'x-marked://open?file=filename.md&raise=true'

Available commands

The following commands are available to the x-marked URL handler.

open

Opens the specified document in Marked.

x-marked://open?file=/Users/username/Desktop/report.md
Parameters:

file (required): The full POSIX path to the document to be opened, or comma-separated list of paths

open also accepts a path whose components will be combined into a single url

x-marked://open/~/nvALT2.2

If the file path provided doesn’t exist or can’t be opened, Marked will still come to the forefront. Running without the file parameter or with a blank value will simply open Marked.

Marked will also open files if only the path of a file is called on the URL handler, e.g. x-marked:///Users/username/Desktop/report.md.

refresh

Refresh a document preview or all open previews.

Parameters:

file: query parameter containing comma-separated paths/filenames. Calling with no file parameter or ?file=all will refresh all open windows.

x-marked://refresh

x-marked://refresh?file=/Users/username/Desktop/report.md

x-marked://refresh?file=report.md

If called with no file parameter but document paths specified in the url, paths split by / will search multiple files, and partial filenames will complete the best match.

x-marked://refresh/filename1/filename2
Parameters:

file (optional): The path (or comma-separated paths) of files currently open in Marked.

Note: If no file parameter is included, Marked will refresh the frontmost document. The file parameter can be partial, Marked will refresh all open windows with a partial match in the filename (not the full path). Passing “all” will refresh all windows.

paste

Create a new document from the current contents of the clipboard.

x-marked://paste
Parameters:

none

Note: This creates a temporary document using the “Preview Clipboard” command. Any text in your clipboard is added to a new, blank document, which is then opened in Marked. If closed without saving, it’s discarded.

preview

Preview specified text in a new document.

x-marked://preview?text=Some%20text%20to%20%2A%2Apreview%2A%2A%0A
Parameters:

text (required): The text to insert into the preview. Percent-encoded text will be unencoded prior to viewing the document.

Note: This creates a temporary document using the “Preview Clipboard” command. The passed text is added to a new, blank document, which is then opened in Marked. If closed without saving, it’s discarded.

style

Set the preview style (CSS) for one or more documents.

Parameters:

css (required): query string containing the name or path of a style. Styles must be present in Marked’s style menu as default or manually-added custom styles.

  • Accepts path parameters referencing names of files, or “all”
  • Paths split by / will search multiple files
  • Partial filenames will complete best match
    x-marked://style/filename1/filename2?css=...
    x-marked://style/all?css=...
    

file: query parameter containing comma-separated paths/filenames

x-marked://style?file=filename1,filename2&css=...

Will operate on frontmost window if a filename is not given (or “all” is not passed)

addstyle

Add a new custom style to Marked.

Parameters:

css: URL encoded CSS text to write to a custom style. Required unless passing a file parameter.

file: Full path (POSIX) to a CSS file to add to Marked. Required unless passing a css parameter.

name: The name of the style to generate.

With the css parameter, this will be used as both the filename when writing to disk, with “.css” added, and the menu item name. It’s required for css parameter, and optional for file (filename will be used as if the name parameter is empty).

x-marked://addstyle?name=My+new+style&css=...

x-marked://addstyle?file=/Users/myuser/Custom+Styles/Unicorn.css

If you include a name with the file parameter, the menu item will get that name instead of the filename. If you use the same name again with a different path, the menu item will be updated with the new path rather than adding a second item with the same name.

do

Run a JavaScript command in a document window.

Parameters:

js (required): query string containing a javascript command

  • Accepts path parameters referencing names of files, or “all”
  • Paths split by / will search multiple files
  • Partial filenames will complete best match
    x-marked://do/filename1/filename2?js=...
    x-marked://do/all?js=...
    

file: query parameter containing comma-separated paths/filenames

x-marked://do?file=filename1,filename2&js=...

Will operate on frontmost window if a filename is not given (or “all” is not passed)

help

Open the Marked internal help system, optionally specifying a topic. This is primarily for use internally, but accessible via URL. A url to any given section can be copied by right clicking on the bookmark icon to the right of a headline and selecting Copy Link.

Parameters:

page (optional): The exact title of an existing page, with optional anchor hash

x-marked://help?page=Document_Statistics

Spaces are replaced with underscores, per the Marked help file naming convention. A colon (:) may be used in place of a hash (#) when specifying an anchor.

The target may be specified by path alone (without query string):

x-marked://help/Keyword_Highlighting:editingkeywords

Search | Support Site | Knowledgebase