Custom Processor

Marked gives you full control.

Using Custom Preprocessors/Processors

To add Custom Processors, go to the Marked Settings, Processor pane and click on Custom Rules.

In the Rules Editor (AKA “Conductor”), you can add custom rules that have criteria to match files based on filename, path, matches in the content, metadata, and even whether other files exist in the same tree as the document being opened. When a rule is matched, the actions defined for the rule are run on that file.

Below the Processor field, the checkboxes in “New documents use custom:” determine whether rules are tested at all for Preprocessor and Processor phases. In general, leave these checked, but if you wan to completely override any custom processors, set that here.

To create a new rule, use the + button at the bottom of the left-hand rules list. Give the rule a name and set it as a preprocessor or a processor:

Preprocessor

Runs after the file is initially processed, when Marked adds included files, handles style preferences like GitHub newlines, etc., but before the processing phase. The document is still raw Markdown at this point and you can make changes to the content to pass to the processor. If no Custom Processor matches, or no Run Processor action is run in a matched Custom Processor, then the default processor will be run.

Processor

A Custom Processor replaces the built-in processor defined in the Marked Settings, Processor pane. It can handle all of the actions that a Preprocessor can, and adds Run Command and Run Processor actions. This allows you to run a custom command, e.g. Pandoc, or run a different built-in processor on files matching the criteria.

All tables in the Custom Rules editor can be reordered by dragging and dropping, so you can affect the order in which rules are run, the order of the criteria in the predicate editor, and the order of actions to be run in sequence.

Predicate Editor

Once a rule is added, use the predicate editor to define criteria that will determine whether the rule is run for a given file. Use the left side dropdown to select a criterion, then use the comparator and value fields to build the predicate.

• filename matches just the filename of the file
• extension matches just the extension of the file
• path matches the full POSIX (Unix) path of the file
• tree searches for filename matches anywhere in the directory tree of the file
• text matches text content in the file. Use forward slashes around the text value to make it a regular expression search.
• fileIncludes tests whether the file contains included files (using any of Marked’s include syntaxes).
• metaType tests whether the file includes YAML, MultiMarkdown, or Pandoc metadata
• metadata.X tests for specific metadata keys like author, date, title, etc.

To match all files (i.e. a Custom Processor that always runs), set filename to contains *. The asterisk will act as a wildcard and match all files.

Actions

Use the + Action button to add actions to the rule. Available actions include:

Set Style

Set the Style for the preview. Any built-in Style or Custom Style you’ve added is available.

Run Command

This takes a command line command, including any arguments, and will pass the content of the file on STDIN. The command should return resulting output on STDOUT.

Run Embedded Script

Edit a full script in the built-in code editor. Like Run Command, this should take input on STDIN and return output on STDOUT.

Set Metadata

Adds or sets metadata. Provide a key and a value. If the key exists, its value will be updated, if not, it will be added. The type of metadata used will be automatically determined by the file’s contents (or the result of a metadata conversion action).

If no existing metadata is found, the metadata will be added in MultiMarkdown format inside of an HTML comment. Marked can read this metadata, but it won’t appear in your preview no matter what processor is used.

Delete Metadata

Delete a metadata based on its key.

Strip Metadata

Delete all metadata. Affects YAML, MultiMarkdown, and Pandoc metadata.

Convert YAML Meta to MMD

Converts a YAML metadata block at the top of the file to MultiMarkdown style metadata.

Convert MMD Meta to YAML

Converts a MultiMarkdown metadata block to YAML.

Search and Replace

Perform a search and replace on the file’s content.

If the search string is surrounded in forward slashes (e.g. /Project \w+/), it will be treated as a regular expression. You can use $1, $2, etc. to include match groups in the replacement string.

Insert Title H1

Inserts an H1 in the document. This can either be pulled from metadata or the filename.

Shift Headers

Adjust header levels, from -5–+5. For example, if you set this to -1, then all H1s become H2s, H2s become H3s, etc. Set it to a positive number to hoist the header levels by that amount.

Normalize Headers

This action will ensure, if possible, that there’s only one H1 in the document, and adjust all header levels so that they’re in a semantic order and don’t skip levels, e.g. from H2 to H4. If the original document is at all semantically ordered to begin with, this will refine the hierarchy well.

Insert TOC

Insert a Table of Contents. The TOC can go after the first H1, the first H2, or at the top of the file (will be inserted after any metadata).

Insert File

Inserts a selected text file at a given point in the document. This can be after the first H1, first H2, top, bottom, or after a text match (use /pattern/ to search for a regular expression).

Insert Text

Provides a popup editor with which you can embed text into the action directly. Positioning options are the same as Insert File.

Insert CSS File

Injects a selected CSS file into the document. This will be loaded after any Style selection and can be used to override existing styles or add new ones.

Insert CSS

Offers a pop-up CSS editor where you can add your own CSS directly to the action. This CSS will be injected at the top of the document, after any existing styles. The order of injected styles will match the order of the actions in the rule.

Insert JavaScript File

Injects a selected JavaScript file at the end of the document. Note that you need to use an Insert JavaScript action with an update hook if you want the script to reload with every update.

Insert JavaScript from URL

Use this to insert a <script> tag linked to a CDN or other remote URL at the end of the document. Note that you need to use an Insert JavaScript action with an update hook if you want the script to reload with every update.

Insert JavaScript

Provides a popup JavaScript editor with which you can embed custom JavaScript directly in the action. This will be injected at the end of the document, and the order of JavaScript run by the rule will be determined by the sequence of the actions, with the last action added last.

Note that you need to use an update hook if you want scripts to run with every update.

Self-Link URLS

Convert any bare urls to <url>, which will generate a hyperlink in any processor.

Run Shortcut

Run an Apple Shortcut. Any Shortcut run should take input from STDIN and return output at the end (Stop and Return Output). If you want to perform actions that don’t modify the text, set the input to a variable, run your actions, and then output the original text variable at the end.

Run System Service

Run any System Service in ~/Library/Services. The Service should accept input and return output.

Run Automator Workflow

Run any Automator .workflow file. Input will be passed on STDIN and output is expected on STDOUT.

Continue

By default, once a rule is matched, processing will stop (separately for Preprocessors and Processors, so one Preprocessor and one Processor can match). This action will force rule matching to continue after the rule performs its actions.

Update Hook

Marked does not do a full refresh with every update, so if you have scripts that render portions of the DOM, they need to run their render function using Marked’s Hook API.

The example below uses Mermaid, which you never actually need to do if the Mermaid option is selected in the Marked Settings, Style pane. But here’s how you would do it if you’re including it manually.

Add an Insert JavaScript action, and in the “Edit JS” window, initialize the script and add the hook:

mermaid.initialize({ startOnLoad: true });

Marked.hooks.register('update', function() {
    mermaid.run();
});

This will cause mermaid.run() to be executed every time Marked performs a partial update.

Test Rules

The Test Rules button under the Rules list will open a dialog where you can select any Markdown file and it will be tested against all of your Rules. Rules that match will get highlighted with a green tab on the left side. When matching against a file, an X button will appear which can be used to clear the test and unhighlight the rows.

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 (or GFM), KRAMDOWN, or COMMONMARK, then that internal processor will be used for just that document. This change will not affect the default processor set in Settings.

Environment variables

The Run Command action has an environment editor where you can set your own environment variables that will be available to the command or script. In addition to these custom variables, Marked includes some of its own.

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

Enabling and Disabling

The custom processors can be turned on and off for individual documents using ⌥⌘C. 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 of the Preview.

Preprocessor

If you set up preprocessor rules, they are 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.

You can specify whether to use custom processor settings 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.

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
-->

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 Run Command path field.

If your processor requires arguments on the command line, you’ll need to enter those in the 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.

A note about Pandoc

Pandoc will not run in the Mac App Store version of Marked. If you need to run Pandoc, use Help->Crossgrade to get a free license for the direct (Paddle) 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 in your Run Command field:

/usr/local/bin/pandoc -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, or use a series of Rules with extensiob matches. If the extension is md, use pandoc -f gfm or pandoc -f markdown_mmd (or just return NOCUSTOM on STDOUT to use the default 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 passing arguments 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 a Custom Rule in Marked Settings, Processor pane to match your AsciiDoc files.
3. Set the Rule to be a Processor and add a Run Command action
   1. Determine the path to asciidoc, which will be something like /usr/bin/asciidoc or /opt/local/bin/asciidoc. If unsure, use which asciidoc to locate
   2. Enter [PATH To asciidoc] --backend html5 -o - - as the command (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