How-tos, tips, and tricks

Using Textile with 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, but the two easiest I’ve found 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. Set your preferences like below for the Perl version. Use /usr/bin/redcloth for RedCloth.
customtextileprocessor.jpg
customtextileprocessor.jpg

Note: your install paths may differ. You can determine the correct path using which textile or which redcloth in the Terminal.

Now Marked is a Textile previewer for you!

If you have trouble with UTF8 characters in your Textile document when using the Perl version, see this gist and edit the /usr/local/bin/textile command, replacing its text with the raw contents of the gist.

Table of contents

Marked Bonus Pack (scripts, commands and bundles)

See the GitHub repository maintained by (kotfu) for information and download.

Table of contents

Custom CSS: Writing custom CSS for Marked

Please see the online help documentation for Creating Custom Styles

Table of contents

Using reStructuredText in Marked

Contributed by Matt Robenolt:

First, install Python’s docutils package.

 $ sudo pip install docutils

In Marked, set the custom processor path to:

 /usr/local/bin/rst2html.py

with the additional arguments set to:

 --no-xml-declaration --stylesheet=

The empty = is intentional. By default, rst2html.py embeds an inline stylesheet to the document. This removes it and allows Marked’s built-in stylesheets to control the preview output.

Table of contents

Using Marked with Github Flavored Markdown and Syntax Highlighting

Built-in support

Marked 1.4 can handle 99% of GitHub previewing for you. Fenced code blocks, syntax highlighting, pixel-perfect Github style simulation and more.

Github Preview

Enable the following preferences:

Preferences->Behavior->Convert Fenced Code Blocks

behavior screenshot
behavior screenshot

Preferences->Style->Automatic syntax highlighting

style screenshot
style screenshot

Fenced code blocks and language specifiers in Github (three or more backticks followed by a language name, with a matched number of backticks for closing the block) or Markdown Extra (tildes instead of backticks, language specifier after the closing tildes) formats will be added as classes to the <pre> element. The automatic syntax highlighting will usually figure out the language regardless of whether you use specifiers, but that way you can write exactly as you would on Github (and your html output will match what you see on Github, too).

The included Github stylesheet has all of the necessary styles to match Github formatting exactly. Set your default style to Github, and set Preferences->Style->Limit text width in Preview to:** to 900px and expand the preview past 900px for exact word wrapping.

Exporting HTML with Syntax highlighting enabled will include the Highlight.js library as well.

Manual installation

To use fully-compatible GitHub Flavored Markdown you need to build your own custom processor with a series of Ruby gems, or take a look at Docter.

Note for rvm/rbenv users:

Marked doesn’t pick up your user environment, so it doesn’t get rvm-type settings. To run Docter or any gem-based script, you’ll need to switch to System ruby and sudo gem install your required gems. Change any hashbangs in scripts to /usr/bin/ruby instead of /usr/bin/env ruby. You should be able to run your script at that point, assuming it doesn’t rely on one of the more recent versions of Ruby that you usually access through rvm. Docter runs fine for me with rvm installed using this method.

You’ll need to install rubygems, which in most systems is available by default. Run gem -v to see if you already have it. Otherwise it can be found at http://rubygems.org/.

Once you have rubygems, you can install the following using gem install [gemname]. Depending on your setup, you may need to use sudo gem install...:

  • redcarpet
  • albino
  • nokogiri
  • pygments.rb

You’ll also need Pygments, a Python tool for syntax highlighting:

  sudo easy_install pygments

You may need to link the pygmentize binary to a location in your path:

  sudo ln -s /usr/local/bin/pygmentize /usr/bin

Once these are in place, create a script based on this one and make it executable (chmod a+x /your/script.rb). Point your “Custom Processor” setting in Marked to the full path to the script (don’t use “~” to shorten your home directory. The easiest way to get this path is to go to the folder where your script is located in Terminal and type pwd|pbcopy, which will put the current path directly on your clipboard. Paste it and add the name of your script to the end of the path.

Note: If you use this method, be sure to disable the features mentioned at the top of this page (fenced code support and syntax highlighting). The built-in Github style has appropriate highlighting styles built in for pygmentized output. You can also disable “Preserve line breaks” as it’s probably handled by your script if you’re using any github-flavored version of Markdown.

Marked has a PWD environment variable that gets set to default system folders and the path to the current working document. If needed you can Dir.chdir(ENV[‘PWD’]) to work from the document directory.

A common error that arises is a lack of RVM support in Marked. Marked currently does not inherit the user environment, so all of your variables disappear. Hardcode the default /usr/bin/ruby into the hashbang, and use $stderr to output any errors you catch.

Table of contents

Using Jekyll with Marked

To get a realistic Jekyll preview for your Jekyll-based blog, see this script, courtesy of @gglanzani.

Some CSS adjustments will be necessary to match your blog output.

Also see http://brettterpstra.com/2013/01/04/previewing-jekyll-posts-with-marked/.

Table of contents

Using Screenplay Markdown with Marked

This is a setup for previewing Screenplay Markdown documents using Marked. This functionality may or may not be built in to a future release of Marked, but you can make full use of it right now using Marked’s customization capabilities.

For the most up-to-date instructions, check out the Candler Blog.

Marked SPMD installation:

  1. Install the files (download here)

    • Double click the .zip file to extract its contents
    • Move marked-screenplain folder to a folder of your choice
    • Suggestions: Your home folder, /usr/local/bin, ~/Library/Application Support/Marked
    • Move the Screenplay.css file to ~/Library/Application Support/Marked/Custom CSS/

  2. Launch Marked and open Preferences

  3. In the Behavior panel, check the Custom Markdown Processor box and in the field below it, enter the path to screenplain_marked

    • This will be the full (no ~) UNIX path. If you put it in /usr/local/bin/ it would be /usr/local/bin/marked-screenplain/bin/screenplain.
    • If you put it in your users’s home folder, it would be: /Users/<username>/marked-screenplain/bin/screenplain

  4. Go to the Style tab of Preferences

    • Click the plus button (+) under the table to add a new custom style
    • In the file select dialog, navigate to ~/Library/Application Support/Marked/Custom CSS/Screenplay Markdown.css and add it

  5. Open a Screenplay Markdown document.

    • The custom processor you entered should be on by default. It can be toggled per-document using the gear menu or ⌥⌘C.
    • Select the “Screenplay Markdown” style from the Style selector in the bottom left.
Notes:
  • This is a customized version of screenplain by Martin Vilcans
  • It creates h2 instead of div for “slug” types to allow for TOC navigation in Preview (hover over the upper right edge of the preview)
  • Currently there are no export abilities for formats other than PDF/HTML
  • Pagination doesn’t work properly just yet. While you can print and export PDFs of your scripts, note that pages will not be numbered and may not accurately render (Characters may be on different pages than their dialogue, no “mores” or “continueds”, etc.). This may be fixed in future updates.

Table of contents

MathJax tips

Contributed by Paul,

This is just a suggestion for people who want to adjust the MathJax behavior to their need and do not want to reply on the choices made in multi markdown. It is not completely satisfactory but works. If you add anywhere in your document (top or bottom being the most obvious) an explicit HTML header (example below) the Marked will use the Mathjax behavior of your choice. Of course do not use “Include MathJax from CDN” in the Preferences or you will get an unpredictable mixture of both the default behavior and yours. Hope this helps Paul %%%% My headers Inserted at the bottom of my docs HTML header should be at the start of a new line of course

HTML header:  <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js">
        MathJax.Hub.Config({
            config: ["MMLorHTML.js"],
            extensions: ["tex2jax.js","TeX/AMSmath.js","TeX/AMSsymbols.js"],
            jax: ["input/TeX"],
            tex2jax: {
                inlineMath: [ ['$','$'], ["\(","\)"] ],
                displayMath: [ ['$$','$$'], ["\[","\]"] ],
                processEscapes: false
            },
            TeX: {
                TagSide: "right",
                TagIndent: ".8em",
                MultLineWidth: "85%",
                equationNumbers: {
                   autoNumber: "AMS",
                },
                unicode: {
                   fonts: "STIXGeneral,'Arial Unicode MS'" 
                }
            },
            showProcessingMessages: false
        });
    </script>'

Table of contents

Custom CSS: Adding chapter numbers with custom CSS

Using the CSS below in either a Custom Style or in the Style Preferences “Additional CSS” field in Marked 2 will add nested numbers before each heading in your document (e.g. 1, 1.1, 1.2, 1.2.1):

body {
    counter-reset: chapter; /* create a chapter counter scope */
}
h1:before {
    content: "Chapter " counter(chapter) ". ";
    counter-increment: chapter; /* add 1 to chapter */
}
h1 {
    counter-reset: subchapter; /* set section to 0 */
}
h2:before {
    content: counter(chapter) "." counter(subchapter) " ";
    counter-increment: subchapter;
}
h2 {
	counter-reset: section;
}
h3:before {
    content: counter(chapter) "." counter(subchapter) "." counter(section) " ";
    counter-increment: section;
}
h3 {
	counter-reset: subsection;
}
h4:before {
	content: counter(chapter) "." counter(subchapter) "." counter(section) "." counter(subsection) " ";
	counter-increment: subsection;
}
h4 {
	counter-reset: subsubsection;
}
h5:before {
	content: counter(chapter) "." counter(subchapter) "." counter(section) "." counter(subsection) "." counter(subsubsection) " ";
	counter-increment: subsubsection;
}
h5 {
	counter-reset: subsubsubsection;
}
h6:before {
	content: counter(chapter) "." counter(subchapter) "." counter(section) "." counter(subsection) "." counter(subsubsection) "." counter(subsubsubsection) " ";
	counter-increment: subsubsubsection;
}

Table of contents

Tricks for working with custom processors

There are myriad options for making custom processors smarter.

First, when you enable a processor or preprocessor, you’ll see small indicators in the bottom menu bar:

If you do not check “automatically enable for new windows,” the indicators will show up as empty outlines. Clicking them will turn the processor (green) or preprocessor (yellow) on or off for the current window only, so you can use it only when needed. Once clicked, the processor will stay on for as long as the window is open (or until you turn it off).

You can also turn a processor or preprocessor on for specific documents automatically using metadata. If you put the following anywhere in your document (it can go inside of HTML comment tags, too) it will set the default for that document:

Custom Processor: true

This works for “custom preprocessor” as well. See Per-document settings in the documentation for more info.

Advanced tricks

You can also, with a little scripting, have your processor auto-detect whether or not it should run. For example, I have a custom processor that checks to see if the document contains YAML headers and certain keys, and if it does it processes it with Kramdown and custom handlers for my own blog. If not, it returns “NOCUSTOM” and processing proceeds as usual without the custom processor. NOCUSTOM returned on STDOUT will cancel the custom processor.

You can use Marked’s available environment variables as variables to determine which of multiple processors to run. For example, checking $MARKED_EXT will return the extension of the document being processed, so you can fork a script to run different processors based on the extension of the file. You can also check the $MARKED_PATH to get the full POSIX path of the current file so you can base logic off of the title or containing folder.

Table of contents

When using iThoughtsX with Marked 2, linking a topic (⌘K) will automatically generate a Markdown link for reading by Marked. In general, this just means you can take it easy and let the apps do the conversion work. However, if you want a link within the text of a topic or note, you need a workaround.

iThoughtsX automatically turns urls into hyperlinks, thus writing Going [home](http://brettterpstra.com). will turn into Going [home]([http://brettterpstra.com](http://brettterpstra.com)).. To make links work in this fashion, both in notes and in topic text, you’ll need to use reference links and place the references in the notes of the main (central) topic. (you can also use notes on a new Floating Topic — e.g. right click->New Floating, call it “References” — though that leaves an extra headline in your preview document).

The trick is that if you put the references in the notes of a sub-topic, they’re indented too far to be recognized as references by the Markdown processor. If you put them in a main topic, they’re only indented 2 spaces (Markdown allows 3), so it works great.

Table of contents

As of version 2.5, Marked can convert Scrivener’s internal link format into Markdown automatically. Links created using Scrivener tools instead of using Markdown syntax are still valid.

However, this means that if Scrivener has auto-linked a url in your Markdown text, it will break any manually-formatted Markdown links. To resolve this, you need to remove the formatting from your text. This can be done by cutting the text, pasting it into TextEdit as a plain text document, and then pasting it back into Scrivener.

Images

Images can be inserted in a document using standard Markdown syntax, with any relative urls referencing the folder containing the Scrivener document (images saved alongside the document, or in a subfolder referenced like ![](subfolder/image.png).

As of Marked 2.5, you can use Scrivener’s image tools to insert an embedded image, and when Marked previews it, it will extract and encode the images to embed in the preview (and HTML, Print, and PDF export formats).

Table of contents

Using AsciiDoc (asciidoctor) in Marked

Contributed by Adrian Kosmaczewski

  1. Make sure that you are not using the ruby that comes by default with macOS, but the one installed with Homebrew. If needed, brew link --overwrite ruby to get everybody in the same line. This means, get rid of rbenv temporarily and then install asciidoctor.
  2. Install asciidoctor and related gems as root (sudo gem install asciidoctor).
  3. Configure Marked 2 using the Preferences > Advanced > Enable Custom Processor option:
    • Path: /usr/local/bin/asciidoctor
    • Args: --base-dir /path/to/your/root/folder/ --safe-mode safe --attribute confdir=../_conf --attribute imagesdir=../images --attribute datadir=../data --attribute codedir=../code --attribute toc --section-numbers --backend html5 --doctype book --out-file - -
      • Pay attention to that double dash with a space at the end of the arguments!
      • It is required to specify the --base-dir and —safe-mode options for asciidoctor, otherwise the images, code and other artifacts are not included properly.

Additional information

Taken from a Gist by Dan Allen.

Marked is an OSX application to preview Markdown syntax in HTML. It’s possible to configure AsciiDoc as an custom Markdown processor to create the HTML for your AsciiDoc files.

Configuration

In the behavior settings of Marked, complete the following steps:

  1. enable Custom Markdown Processor

  2. enter path to asciidoc command (something like /usr/bin/asciidoc or /opt/local/bin/asciidoc)

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

Resolving include files

One of the hiccups with using AsciiDoc with Marked are include files, such as:

include::myfile.txt[]

The asciidoc command dies when it hits the first include file, since it tries to resolve it from the working directory, which probably isn’t the directory of your document.

Here are a few ideas for how to work around this problem.

Option A

You can switch the current working directory to the directory of your document using a shell script (or commandline chain) that wraps the asciidoc command. You would need some way for Marked to pass the directory of the document so the script knows where it needs to switch.

Option B

You can set the absolute include directory as an attribute in your AsciiDoc document, then prefix all include paths with this attribute. For example:

= Document Title
:includedir: /path/to/document/
    
Unresolved directive in <stdin> - include::{includedir}myfile.txt[]

You can override the includedir attribute from the commandline when you process the document in a different context. Consider the setting in the document as the fallback. Another option is to add it to the args to the custom markdown processor, such as -a includedir=/path/to/document/.

Option C

You can use Asciidoctor, which allows you to set the base directory from the commandline. I’m not sure how to get the document directory from Marked, so let’s just assume for now that you have to hard code it. You would specify the path to asciidoctor instead of asciidoc and append the following to the args: -B /path/to/documents

Asciidoctor has the benefit that it’s about 40x as fast as AsciiDoc. For instance, the 17,000 line (3,750 blocks) Enterprise Web Book from O’Reilly renders to HTML5 in 0.85 seconds on an ASUS ZenBook Prime notebook :)

Reference: Using AsciiDoc with Marked (Google discussion post)

Table of contents

Using Monodraw with Marked

Monodraw output relies on specific fonts with Unicode characters, so it doesn’t work with some of Marked’s styles. To resolve this, add the following to **Preferences->Style->Additional CSS" (or to your custom css style):

pre code {
    font-family: Menlo, Georgia, Garamond, serif !important;
    font-size: 50%;
}

via Peter Shannon

Table of contents

Using JavaScript in Marked

Marked uses a lot of Javascript to provide the features it offers in the preview. For this reason, complications can arise when scripts are included within the body of the document.

External scripts

You can include some external scripts using a “CSS Header:” metadata line at the top of your document. These scripts will be inserted not in the header, though, but in the footer after jQuery and Marked’s scripts have already loaded. This is ideal in most cases. You may still experience unexpected behavior, as Marked can’t compensate for every possible scripting conflict. DOM changes can be especially problematic.

CSS Header: <script src="file.js"></script>

Inline includes

There are many applications for having Javascript appear in the body of a document, such as graph generators or other Canvas tools. Depending on configuration settings and the processor you’re using, these are often mangled. The solution is to put your script and extra DOM elements into an external file and use Marked’s syntax for “raw” include files (<<{file}, with curly brackets). These files are not processed in any way; their contents are added into the file after the rest of the processing is complete.

Markdown text.

<<{file.html}

More Markdown text...

Table of contents

Custom CSS: Customizing checkboxes

Marked supports GitHub-style checkboxes in lists using the syntax:

 - [ ] Unchecked item
 - [x] Checked item

To enable this, turn on Preferences->Processor->Render GitHub checkboxes.

Checkboxes will be rendered in standard GitHub formatting, but you can customize them with CSS (either in a custom style or in Preferences->Style->Additional CSS). Here’s an example for creating image-based checkboxes.

#wrapper .task-list .task-list-item input[type=checkbox] {
	overflow: visible;
	height: 1px;
	width: 1px;
	padding: 0;
	border: 0;
	position: absolute;
	margin-left: -2em;
}

#wrapper .task-list .task-list-item input[type=checkbox]:checked:before {
	background-position: 0 -15px;
}

#wrapper .task-list .task-list-item input[type=checkbox]:before {
	content: ' ';
	padding-left: 20px;
	height: 15px;
	display: inline-block;
	line-height: 15px;
	background-repeat: no-repeat;
	background-position: 0 0;
	font-size: 15px;
	vertical-align: middle;
	cursor: pointer;
	background-image: url(http://csscheckbox.com/checkboxes/dark-plus-cyan.png);
	position: absolute;
}

Table of contents

Using Ulysses with Marked

In Ulysses, dragging a file from the sheet list to Marked 2 will only work for files within “External Folders.” Internal Ulysses documents are not stored on disk in a way that Marked 2 can read, and the preview only shows up initially because when dragging out Ulysses creates a temporary preview that is overwritten after changes.

To preview selected Ulysses sheets in Marked, use the Quick Preview (⌘6).

  1. Press ⌘6 to open the Quick Preview palette
  2. Select “Text” as the preview type from the dropdown at the top
  3. Set the format to “Textbundle”
  4. Use the dropdown on the right side of the button at the bottom to choose Marked 2*

* If there’s not a dropdown arrow visible, use the Tab key to rotate through the default action options until you get to Open In…

Once these are set, typing ⌘6 and pressing Return will open/update the preview in Marked. Because Ulysses isn’t saving files to disk that you can watch, you’ll need to use this key sequence when you want to update the preview in Marked 2.

Screen_Shot_2020-09-25_at_12.12.07_PM.png
Screen_Shot_2020–09–25_at_12.12.07_PM.png

Table of contents

Highlight sentences longer than a certain number of words

You can use Marked’s keyword highlighting features to highlight sentences exceeding a certain number of words. This can be modified to work with other requirements as well, if you know a bit about regular expressions.

By surrounding any keyword search term with forward slashes, you can use a regular expression instead of a string. This regex will highlight any sentence longer than 25 words:

/(?!\s)([^.!?]+?\s){25,}(?![\.!?])\w+/

(You can adjust the {25,} to your needs, e.g. {30,} for sentences longer than 30 words.) Test it out by opening the keyword highlight panel (⇧⌘K or Gear Menu > Proofing > Keyword Drawer) and pasting it into the Temporary Keywords field. Clicking the green “play” button or pressing ⌘↩ (command return) will run the search and highlight offending sentences in green.

If it works, you can add it as a permanent search by going to Preferences->Proofing and choosing which list you’ll add the regular expression to. The list determines what color it will be highlighted with and to which counter it will be added. I’d say this would go under “Avoid.”

Now when you turn on highlighting, long sentences will show up in red.

Table of contents

Next up: Preview Not Updating ▶

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