Marked gives you full control.
Using a custom processor/preprocessor
You can specify a custom Markdown processor in the. 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.
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:
When enabled, the custom preprocessor can be turned on and off for individual documents using ⌃⌥⌘C.
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 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.
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 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.
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:
- The location (base directory) of your primary working file (the folder of the working text, Scrivener or index file).
- 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).
- 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.
- 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.
- This is the full UNIX path to the main file open in Marked when at the time it’s loaded.
- A quoted, comma-separated list of the files Marked has included in the text being passed using the various include syntaxes.
- This will be set to either “PROCESS” or “PREPROCESS,” allowing you to use a single script to handle both phases based on this variable.
- 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.
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 processors documentation for details.
I’ve tested the Custom Processor feature with Pandoc, kramdown, marked (discount), MultiMarkdown 6, maruku, and various and sundry 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. When I get around to posting an example script, I’ll add a link here.
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:
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:
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
pandoc -f gfm or
pandoc -f markdown_mmd (or just return
NOCUSTOM on STDOUT to use Marked’s internal processor). But if it’s
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.
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:
- Install Textile from https://github.com/bradchoate/text-textile OR
sudo gem install RedClothin Terminal
which redclothto determine the path to use in the Custom Processor path settings
Now Marked is a Textile previewer for you!
- Install AsciiDoctor.
- Enable the Custom Markdown Processor in the
- enter path to asciidoc command (something like
/opt/local/bin/asciidoc. If unsure, use
which asciidocto locate.)
--backend html5 -o - -as args (the - at the end sends the output as STDOUT)
- enter path to asciidoc command (something like
This sends the current document to STDIN and displays the generated HTML as STDOUT.