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.

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'

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 affected window(s) will raise above all other windows (all applications) before returning or executing a callback.

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

Available commands

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

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.

defaults

Set user preferences. Accepts a list of keys and values as query parameters. Only existing keys will be set. If the preference change requires a refresh, all windows will refresh automatically unless refresh=0 is passed.

Use 1 for true and 0 for false on boolean values.

Parameters:

refresh (optional): if set to 0, automatic refresh of open preview windows is disabled

  • Default: 1 (true)
Example:
x-marked://defaults?syntaxHighlight=1&includeMathJax=0

The defaults method is mostly designed so that the developer can add links to esoteric features that might not otherwise be available in preferences. There might be some standard options you’d want to toggle when automating, though. Some common preferences you might want to control during automation:

syntaxHighlight
enable or disable syntax highlighting
includeMathJax
enable or disable internal MathJax handling
processor
set to multimarkdown or mmd to change the processor to MultiMarkdown, discount or gfm to use the Discount (GFM) processor
h1IsPageBreak, h1IsPageBreak, breakBeforeFootnotes
Automatic page breaks in export before header levels 1 and 2, and footnotes.

do

Run a JavaScript command in a document window. Marked’s entire JavaScript API is documented here.

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

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.

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.

refresh

Refresh a document preview or all open previews.

Parameters:

file: query parameter containing comma-separated paths/filenames (files must be currently open in Marked). Calling with no file parameter or ?file=all will refresh all open windows.

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.

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

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)

Next up: Workflow Integration ▶

Search | Support Site | Knowledgebase | Legal | Privacy | Twitter