Awesome

MMark CLI

Templates
Extensions
Contribution
License

This is a command line application serving as an interface to the MMark markdown processor.

mmark—command line interface to MMark markdown processor

Usage: mmark [-v|--version] [-i|--ifile IFILE] [-o|--ofile OFILE] [-j|--json]
             [-t|--template FILE] [--ext-comment PREFIX] [--ext-font-awesome]
             [--ext-footnotes] [--ext-kbd] [--ext-link-target] [--ext-mathjax]
             [--ext-obfuscate-email CLASS] [--ext-punctuation]
             [--ext-skylighting] [--ext-toc RANGE]
  Command line interface to MMark markdown processor

Available options:
  -h,--help                Show this help text
  -v,--version             Print version of the program
  -i,--ifile IFILE         Read markdown source from this file (otherwise read
                           from stdin)
  -o,--ofile OFILE         Save rendered HTML document to this file (otherwise
                           write to stdout)
  -j,--json                Output parse errors and result in JSON format
  -t,--template FILE       Use the template located at this path
  --ext-comment PREFIX     Remove paragraphs that start with the given prefix
  --ext-font-awesome       Enable support for inserting font awesome icons
  --ext-footnotes          Enable support for footnotes
  --ext-kbd                Enable support for wrapping things in kbd tags
  --ext-link-target        Enable support for specifying link targets
  --ext-mathjax            Enable support for MathJax formulas
  --ext-obfuscate-email CLASS
                           Obfuscate email addresses assigning the specified
                           class
  --ext-punctuation        Enable punctuation prettifier
  --ext-skylighting        Enable syntax highlighting of code snippets with
                           Skylighting
  --ext-toc RANGE          Enable generation of table of contents using the
                           supplied range of headers to include, e.g. "1-6" or
                           "2-4"

Templates

By using the --template argument, it's possible to create a standalone HTML page. The templating system we use is Mustache, as implemented by the stache library. The library conforms to the version 1.1.3 of the official Mustache specification, but does not implement lambdas (which is an optional feature is the specification) for simplify and other technical reasons we won't touch here.

If markdown source file has a YAML section, its contents will be provided as context for rendering of the template. In addition to that, a new top-level value bound to the variable named output will be available. That variable contains the HTML rendition of markdown document. It's best to interpolate it without HTML escaping, like so: {{& output }}.

Extensions

Here we list how to use the available extensions. The extensions come from the mmark-ext package.

Comment paragraph

Option: --ext-comment PREFIX

This extension removes paragraphs that start with the given PREFIX. For example:

$ mmark --ext-comment REM
First.

REM Second.

Third.
----------------------- Control-D
<p>First.</p>
<p>Third.</p>

Font awesome

Option: --ext-font-awesome

This allows us to turn autolinks with fa scheme into font awesome icons:

$ mmark --ext-font-awesome
Here is the user icon: <fa:user>.

A more interesting example: <fa:quote-left/3x/pull-left/border>.
----------------------- Control-D
<p>Here is the user icon: <span class="fa fa-user"></span>.</p>
<p>A more interesting example:
  <span class="fa fa-quote-left fa-3x fa-pull-left fa-border"></span>.
</p>

In general, all path components in URIs that go after the name of icon will be prefixed with "fa-" and added as classes, so you can do a lot of fancy stuff, see http://fontawesome.io/examples/.

Footnotes

Option: --ext-footnotes

The extension performs two transformations:

It turns links with URIs with footnote scheme and single path piece consisting of a number into links to footnote references.
It turns block quotes with the "footnotes" label (see the example below) into a footnote section.

$ mmark --ext-footnotes
Here goes some text [1](footnote:1).

> footnotes

  1. Here we have the footnote.
----------------------- Control-D
<p>Here goes some text <a href="#fn1" id="fnref1"><sup>1</sup></a>.</p>
<ol>
<li id="fn1">
Here we have the footnote.
<a href="#fnref1">↩</a></li>
</ol>

The extension is not fully safe though in the sense that we can't check that a footnote reference refers to an existing footnote and that footnotes have corresponding references, or that they are present in the document in the right order.

Kbd tags

Option: --ext-kbd

Introduce kbd tags into resulting HTML document by wrapping content in links with URL with kbd scheme. For example:

$ mmark --ext-kbd
To enable that mode press [Ctrl+A][kbd].

[kbd]: kbd:
----------------------- Control-D
<p>To enable that mode press <kbd>Ctrl+A</kbd>.</p>

The use of reference-style links seems more aesthetically pleasant to the author, but you can of course do something like this instead:

To enable that mode press [Ctrl+A](kbd:).

Link targets

Option: --ext-link-target

When title of a link starts with the word "_blank", "_self", "_parent", or "_top", it's stripped from title (as well as all whitespace after it) and added as the value of target attribute of the resulting link. For example:

$ mmark --ext-kbd
This [link](/url '_blank My title') opens in new tab.
----------------------- Control-D
<p>This <a href="/url" title="My title" target="_blank">link</a>
opens in new tab.</p>

MathJax

Option: --ext-mathjax

The extension allows us to transform inline code spans into MathJax inline spans and code blocks with the info string "mathjax" (case-sensitive) into MathJax display spans. Every line in such a code block will produce a separate display span, i.e. a separate line with a formula (which is probably what you want anyway).

Inline code spans must start and end with the dollar sign $ to be recognized as MathJax markup:

$ mmark --ext-mathjax
Let's talk about `$A$` and `$B$`.

```mathjax
A \xrightarrow{f} B
```
----------------------- Control-D
<p>Let&#39;s talk about
  <span class="math inline">\(A\)</span> and
  <span class="math inline">\(B\)</span>.
</p>
<p>
  <span class="math display">\[A \xrightarrow{f} B\]</span>
</p>

Email obfuscation

Option: --obfuscate-email CLASS

This extension makes email addresses in autolinks be rendered as something like this:

[mark@arch ~]$ mmark --ext-obfuscate-email protected-email
Send all your spam to <someone@example.org>, if you can!
----------------------- Control-D
<p>Send all your spam to
  <a href="javascript:void(0)"
     class="protected-email"
     data-email="someone@example.org">
  Enable JavaScript to see this email</a>, if you can!
</p>

You'll also need to include jQuery and this bit of JS code for the magic to work:

$(document).ready(function () {
    $(".protected-email").each(function () {
        var item = $(this);
        var email = item.data('email');
        item.attr('href', 'mailto:' + email);
        item.html(email);
    });
});

Punctuation prettifier

Option: --ext-punctuation

This makes MMark prettify punctuation (only affects plain text in inlines), the effect is the following:

Replace ... with ellipsis …
Replace --- with em-dash —
Replace -- with en-dash –
Replace " with left double quote “ when previous character was a space character, otherwise replace it with right double quote ”
Replace ' with left single quote ‘ when previous character was a space character, otherwise replace it with right single quote ’ aka apostrophe

For example (not sure if this is the correct punctuation to use here, but it demonstrates the effect):

$ mmark --ext-punctuation
Something---we don't know what, happened...
----------------------- Control-D
<p>Something—we don’t know what, happened…</p>

GHC syntax highlighter

Option: --ext-ghc-highlighter

Use the GHC syntax highlighter package to highlight code blocks with "haskell" info string using lexer of GHC itself.

The resulting HTML will be rendered as described here.

Example:

$ mmark --ext-ghc-highlighter
Some Haskell:

```haskell
main :: IO ()
main = return ()
```
----------------------- Control-D
<p>Some Haskell:</p>
<div class="source-code"><pre><code class="language-haskell">
<span class="va">main</span><span> </span><span class="sy">::</span><span> </span><span class="cr">IO</span><span> </span><span class="sy">(</span><span class="sy">)</span><span>
</span><span class="va">main</span><span> </span><span class="sy">=</span><span> </span><span class="va">return</span><span> </span><span class="sy">(</span><span class="sy">)</span><span>
</span></code></pre></div>

Skylighting

Option: --ext-skylighting

Use the skylighting package to render code blocks with info strings that result in a successful lookup from the syntax table that comes with the library.

The resulting HTML will be rendered as described here.

Example:

$ mmark --ext-skylighting
Some Haskell:

```haskell
main :: IO ()
main = return ()
```
----------------------- Control-D
<p>Some Haskell:</p>
<div class="source-code"><pre><code class="language-haskell">
<span class="ot">main ::</span><span> </span><span class="dt">IO</span><span> ()</span>
<span>main </span><span class="fu">=</span><span> return ()</span>
</code></pre></div>

Option: --ext-toc RANGE

Replace the code block with info string "toc" by table of contents assembled from headings with levels from N to M, where N-M is RANGE.

For example:

$ mmark --ext-toc 2-4
# Story of my life

```toc
```

## Charpter 1

Foo.

## Chapter 2

Bar.

### Something

Baz.
----------------------- Control-D
<h1 id="story-of-my-life">Story of my life</h1>
<ul>
<li>
<a href="#charpter-1">Charpter 1</a>
</li>
<li>
<a href="#chapter-2">Chapter 2</a>
<ul>
<li>
<a href="#something">Something</a>
</li>
</ul>
</li>
</ul>
<h2 id="charpter-1">Charpter 1</h2>
<p>Foo.</p>
<h2 id="chapter-2">Chapter 2</h2>
<p>Bar.</p>
<h3 id="something">Something</h3>
<p>Baz.</p>

Contribution

Issues, bugs, and questions may be reported in the GitHub issue tracker for this project.

Pull requests are also welcome.

License

Distributed under BSD 3 clause license.