Custom Processor

Marked gives you full control.

See the Custom Processor overview video on YouTube.

Marked Conductor

The easiest way to implement custom processors is with the Marked Conductor. It allows you to use YAML configuration to run commands and scripts, as well as “filters” for easily performing tasks like injecting styles and javascript into documents. It allows for the creation of “tracks,” which branch the processor based on easy criteria like filename, extension, parent folders, or YAML/MMD metadata. Check out the Conductor page for details, and see the sample config for examples.

Using a custom processor/preprocessor

You can specify a custom Markdown processor in the Marked 2 Preferences, Advanced pane. Enter a UNIX path to an executable or script which can take input on STDIN and return output on STDOUT and it will be used for Preview, Source, Print and Save operations. This can, for example, allow Maruku or Kramdown to be used instead of MultiMarkdown, or even incorporate Textile and other markup languages into Marked.

If your custom processor needs additional arguments, specify them in the next field, separating each argument with a space (just like you would on the command line). If your process is more complicated than a single command, create a self-contained script, make it executable and point the Custom Processor to it.

Checking the “Use by default” box will determine whether the Custom Processor is turned on when a document first loads. If you only need your custom processor for certain documents, uncheck this box to have Marked function as usual until the custom processor is manually enabled for an opened document.

When enabled in preferences, the custom processor can be turned on and off for individual documents using ⌥⌘C. Note the Use by default setting, which will determine if the custom pre/processor is turned on automatically for new documents.

You can also turn a preprocessor or processor on for a document automatically using metadata at the top of the document.

The current statuses of the processors for each document are displayed as indicator lights (only visible when a processor is enabled) to the left of the toolbar items in the bottom right toolbar.

Preprocessor

If you set up a preprocessor, it is run after Marked handles any Marked-specific tasks such as including external documents and code, but before it runs the processor (internal or custom). This gives you a chance to render custom template variables, handle substitutions or inject your own content by any other means.

Marked sets an environment variable for the working directory (MARKED_ORIGIN) to the parent directory of the file being previewed. You can use this to change the working directory of a script and include files with paths relative to the original document. As an example, in Ruby you can use:

Dir.chdir(ENV['MARKED_ORIGIN'])

When enabled, the custom preprocessor can be turned on and off for individual documents using ⌃⌥⌘C.

Per-document Processor/Pre-processor

Custom Processors can also be set on a per-document basis using the metadata format for Per-Document settings.

Custom processors and pre-processors (a script to run on the compiled text prior to rendering it with MultiMarkdown, Discount or your custom processor) can be set in the Marked 2 Preferences, Advanced pane. You can specify whether to use the custom processor listed in preferences and override the default for a document using Per-Document settings (Custom Processor: and Custom Preprocessor:). Any setting other than “true” or “yes” will disable the custom pre/processor. For now, the Preprocessor will only work with the single custom preprocessor you set up in Preferences.

Example usage:

Custom Processor: true
Custom Preprocessor: false

As noted in the Per-Document Settings page, you can surround this metadata with HTML comment markers to hide it from Github and other processors that don’t remove it from the output:

<!--
Custom Processor: true
Custom Preprocessor: true
-->

Processor and Preprocessor metadata can also be a JSON array, allowing you to specify arguments for the pre/processor that override any set in Preferences. The fist element in the array must be “true” or “false” to determine whether the processor is used. Each space in the arguments should begin a new element in the array:

Custom Processor: [true, "-o", "html"]

Dynamically bypassing custom processors

If a custom processor returns “NOCUSTOM” on STDOUT, Marked will terminate the custom processor and fall back to the default internal processor. This allows you to create a custom processor that can decide whether or not it needs to run using the environment variables below, the document filename or extension, content matching or other logic.

If instead of “NOCUSTOM” a Custom Processor returns “MULTIMARKDOWN” or “DISCOUNT”, then that internal processor will be used for just that document. This change will not affect the default processor set in Preferences.

Environment variables

Marked runs the custom processor in its own shell, meaning standard environment variables are not automatically passed. You can use Marked’s environment variables to augment your own in your scripts. Marked makes the following variables available for use in your shell scripts:

MARKED_ORIGIN
The location (base directory) of your primary working file (the folder of the working text, Scrivener or index file).
PATH
Marked sets a path which includes default executable folders and appends the directory in the MARKED_ORIGIN above. The defaults are: /Developer/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin. You can add your own by setting the PATH variable as needed and appending or overwriting Marked’s path (e.g. PATH=/usr/local/yourfolder:$PATH).
HOME
The home directory of the logged-in user. Python and other scripts which rely on the HOME variable being set will pick this up automatically, but it’s available for other uses in your scripts.
MARKED_EXT
The extension of the primary file being processed. This variable allows you to script different processes based on the type of file being viewed. For example, if $MARKED_EXT == "md" run your preferred Markdown processor, but if $MARKED_EXT == "textile" run a Textile processor.
MARKED_PATH
This is the full UNIX path to the main file open in Marked when at the time it’s loaded.
MARKED_INCLUDES
A quoted, comma-separated list of the files Marked has included in the text being passed using the various include syntaxes.
MARKED_PHASE
This will be set to either “PROCESS” or “PREPROCESS,” allowing you to use a single script to handle both phases based on this variable.
MARKED_CSS_PATH
The full path to the current stylesheet

Using an alternative Markdown processor

Any Markdown flavor you can render from the command line can be used with Marked. It needs to be able to take input on STDIN, which is the same as “piping” your Markdown to it on command line, i.e. cat myfile.md | myprocessor. It needs to return the resulting HTML on STDOUT, which every processor I’ve ever worked with does by default.

Use which YOUR_PROCESSOR in Terminal to determine the path to the executable, then paste that into the Custom Processor path field. When you tab out of the field, it should present “OK” next to the field to indicate processor is found and determined to be executable.

If your processor requires arguments on the command line, you’ll need to enter those in the arguments field as well. Some processors need hyphens to function on STDIN and/or STDOUT, e.g. -o - - often signals input from STDIN, output to STDOUT. See your processor’s documentation for details.

I’ve tested the Custom Processor feature with Pandoc, kramdown, marked (discount), MultiMarkdown 6, maruku, and various other flavors. As a side note, I have a “mother” script that branches to different flavors based on variables like file location, YAML data, and text content. It’s a highly useful technique.

A note about Pandoc

Pandoc will not run in the Mac App Store version of Marked. If you need to run Pandoc, set it up in Preferences and when it attempts to run, it will walk you through the steps to request a free crossgrade to the direct version. This is true of any processor that runs into sandboxing issues: if Marked can’t execute it due to MAS permissions issues, it will offer the steps to crossgrade. If you’re experiencing issues and this isn’t happening, please contact me through the support site.

Pandoc as Swiss Army Markdown Processor

Pandoc is by far the most flexible all-purpose tool for handling an array of markup formats. By adding a -f argument with one of the following, Pandoc can be your Custom Processor for any of:

  • commonmark
  • docbook
  • dokuwiki
  • gfm
  • markdown_phpextra
  • mediawiki
  • textile
  • twiki
  • vimwiki

And a bunch of others. See the Pandoc documentation for more info. To use one of these as an input format, just add the following as your Custom Processor:

  • Path: /usr/local/bin/pandoc
  • Arguments: -f INPUT_FORMAT

Pandoc is perfect for writing a script that uses the $MARKED_EXT environment variable to determine which format to run through pandoc. If the extension is md, use pandoc -f gfm or pandoc -f markdown_mmd (or just return NOCUSTOM on STDOUT to use Marked’s internal processor). But if it’s textile, run pandoc -f textile within the script. And if it’s wiki, use one of the wiki markup processors. You get the idea.

As Pandoc afficionados will know, Pandoc can also handle extensive bibliography and LaTeX scenarios. Most features you can access through the command line are available just by using the Arguments field in Marked.

Using Textile

A few people have asked how to get Textile working in Marked. You need to have a Textile converter available from the command line. There are a few options, including Pandoc (see above), but if you don’t already have Pandoc installed, two other options are RedCloth for Ruby and Textile for Perl (requires that the Developer Tools be installed). Install one or the other:

  1. Install Textile from https://github.com/bradchoate/text-textile OR sudo gem install RedCloth in Terminal
  2. Use which textile or which redcloth to determine the path to use in the Custom Processor path settings

Now Marked is a Textile previewer for you!

Using AsciiDoc

  1. Install AsciiDoctor.
  2. Enable the Custom Markdown Processor in the Marked 2 Preferences, Advanced pane
    1. enter path to asciidoc command (something like /usr/bin/asciidoc or /opt/local/bin/asciidoc. If unsure, use which asciidoc to locate.)
    2. enter --backend html5 -o - - as args (the - at the end sends the output as STDOUT)

This sends the current document to STDIN and displays the generated HTML as STDOUT.

See this gist from Dan Allen for more information.

Next up: Creating Custom Styles ▶

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