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

There’s a repository for Custom Styles on Github. Feel free to browse, use, and contribute there. If you distribute your theme based on one of the base themes, please feel free to add yourself to the credits as a contributor.

With Marked’s ability to use custom CSS files, the sky’s the limit when customizing your Preview. All CSS3 options that work in Safari will work in Marked. With default Markdown files in Marked there are only a few HTML elements you need to handle; all of the content is in a div with the id of “wrapper”, everything else is determined by your document markup.

If you’re designing for personal use, there are no rules. Turn on CSS tracking with the checkbox below the custom CSS selector and when you edit and save your custom CSS, it will update the preview.

A skeleton theme is available for getting started.

If you’re planning to share your CSS creation, there are a few points you need to cover. First, there are some body classes that need to have styles applied:

Body classes

The following styles must be included in any Marked CSS to be shared. The body classes allow you to target and modify any selector under different preference options.

Inverted

When the user selects “Invert colors” in Preferences, a class of “inverted” is added to the body tag. You can use this to target the high-contrast, light on dark styles.

You only want inverted styles to apply to the preview, not to print, so use a media query (@media screen) to restrict it. The code below is fairly all-purpose and in most cases you can just drop it into your stylesheet for compatibility, but feel free to tweak it.

@media screen {
    .inverted, .inverted #wrapper { background:#111 !important }
    .inverted p,.inverted td,.inverted li,.inverted h1,.inverted h2,
    .inverted h3,.inverted h4, .inverted h5, .inverted h6, .inverted pre,
    .inverted code,.inverted th {
        color:#eee !important;
    }
    .inverted a { color:#fff;text-decoration:underline }
    #wrapper {
        background: transparent;
        padding:20px;
    }

}

Poetry

The user can choose whether tab-indented text is poetry or code. The only difference is that pre/code blocks are styled more, um, poetically if poetry mode is chosen. The “poetry” class is applied to the body tag.

Get as creative as you like with the formatting, but here’s a basic snippet:

.poetry pre code {
    font-family:Georgia, Garamond, serif;
    font-style:italic;
    font-size:110% !important;
    line-height:1.6em;
    display:block;
    margin-left:1em;
}

Special cases

Tables, Figure/Figcaption, and the special case of a.footnote and div.footnotes>a also need to be considered. There are no set rules on how you handle them, but take a look at the default styles to get an idea what CSS rules Marked needs.

The standard table styling across all of the default styles uses transparency on the alternating rows to make it blend softly with any background. You can copy those styles, or go your own route, just make sure you’ve styled them! Same for figure and figcaption; add an image to a document with alt text to see how the markup will come out and style appropriately.

Footnotes included in a document will render a link within the content (a.footnote), and a div at the end with the referenced text (div.footnotes). Again, see the default styles for reference. To avoid changing the line height on lines containing a footnote reference number, be sure to include something like:

sup,sub,a.footnote {
    font-size: 1.4ex;
    height: 0;
    line-height: 1;
    vertical-align: super;
    position: relative;
}

To keep the return arrow on the same line, include:

.footnotes p {display:inline}

It’s also a good idea to include a general rule for all images to keep them within the width of the page. Something like:

#wrapper img { max-width: 100% }

If your theme has additional padding or a fixed width, modify the max-width to fit.

Print styles

Be sure to include print styles that remove any background colors, fixed scrolling, etc. Use “@media print” to define them within your theme.

Link-hiding in print is handled outside of the main theme, allowing users to choose to have link highlights and underlines hidden in printout. As long as you have a base style set for the text, you don’t need to worry about this.

So, have at it. Convert your blog theme, create a killer print style for PDF documents, or craft the perfect preview for the style of writing you do. If you make something awesome, let me know and I’ll post it for the whole Marked community.

Additional CSS Preferences

In the Style Preference pane, you can edit additional CSS. These styles will be appended to any theme loaded, and can be used to make universal changes to all themes.

Using high specificity and @media queries for print and screen, you can control just about every styling aspect with a bit of CSS knowledge.

Webkit Inspector

Use ^⌥I or right click on your preview window and select “Inspect Element” to launch the Webkit Inspector. This is an easy way to see what elements exist and what CSS rules are affecting them. You can even make edits within the Inspector to see how the results will look. See Apple’s Developer Tools documentation for more information on the Webkit Inspector.

Other tips

Overriding specificity

Within the Marked preview, a body class based on the filename of the current style is added. If the preview is set to “Swiss”, then there will be a class on the <body> tag called ‘mkstyle–swiss’. If your custom CSS is called MyCustom.css, then the body class will be ‘mkstyle–mycustom’. You can use this before rules defined in the base styles to override them. To get absolute specificity in a rule, use the #wrapper ID from the container div as well:

.mkstyle--mycustom #wrapper p+p { ... }

Table of contents styling

If you use the <!--toc--> token to insert a table of contents, you can override the preferences for Table of Contents level indicators in a Custom Style using the “#wrapper” to increase specificity:

 #wrapper #mkreplaced-toc li {
   list-style-type: square;
 }

This would make all of the list items in the Table of Contents use a square bullet instead of what was set in preferences when your Custom Style is active.

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}). 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 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

Once these are set, typing ⌘6 and pressing Return will open/update the preview in Marked. This will need to be done manually any time you want to update the preview in Marked 2.

Table of contents


Search | Support Site | Knowledgebase