Module documentation for 0.0.5.2

There are no documented modules for this package.

MMark CLI

• Templates
• Extensions
  • Comment paragraph
  • Font Awesome
  • Footnotes
  • Kbd tags
  • Link targets
  • MathJax
  • Email obfuscation
  • Punctuation prettifier
  • GHC syntax highlighter
  • Skylighting
  • Table of contents
• Contribution
• License

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

mmark—command line interface to MMark markdown processorUsage: 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 processorAvailable 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 standaloneHTML page. The templating system we use isMustache, as implemented bythestache library. Thelibrary conforms to the version 1.1.3 of the officialMustachespecification, but does not implementlambdas (which is an optional feature is the specification) for simplify andother technical reasons we won’t touch here.

If markdown source file has a YAML section, its contents will be provided ascontext for rendering of the template. In addition to that, a new top-levelvalue bound to the variable namedoutput will be available. That variablecontains the HTML rendition of markdown document. It’s best to interpolateit without HTML escaping, like so:{{& output }}.

Extensions

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

Comment paragraph

• Option:--ext-comment PREFIX

This extension removes paragraphs that start with the givenPREFIX. Forexample:

$ mmark --ext-comment REMFirst.REM Second.Third.----------------------- Control-D<p>First.</p><p>Third.</p>

Font awesome

• Option:--ext-font-awesome

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

$ mmark --ext-font-awesomeHere 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 willbe prefixed with"fa-" and added as classes, so you can do a lot of fancystuff, seehttp://fontawesome.io/examples/.

Footnotes

• Option:--ext-footnotes

The extension performs two transformations:

• It turns links with URIs withfootnote scheme and single path piececonsisting 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-footnotesHere 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 thata footnote reference refers to an existing footnote and that footnotes havecorresponding references, or that they are present in the document in theright order.

Kbd tags

• Option:--ext-kbd

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

$ mmark --ext-kbdTo 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 theauthor, 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 allwhitespace after it) and added as the value oftarget attribute of theresulting link. For example:

$ mmark --ext-kbdThis [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 inlinespans and code blocks with the info string"mathjax" (case-sensitive) intoMathJax display spans. Every line in such a code block will produce aseparate display span, i.e. a separate line with a formula (which isprobably what you want anyway).

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

$ mmark --ext-mathjaxLet's talk about `$A$` and `$B$`.```mathjaxA \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 somethinglike this:

[mark@arch ~]$ mmark --ext-obfuscate-email protected-emailSend all your spam to <[email protected]>, if you can!----------------------- Control-D<p>Send all your spam to  <a href="#"/cdn-cgi/l/email-protection" data-cfemail="14677b79717b7a7154716c75796478713a7b6673">[email protected]">  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 towork:

$(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 spacecharacter, otherwise replace it with right double quote”
• Replace' with left single quote‘ when previous character was a spacecharacter, otherwise replace it with right single quote’ aka apostrophe

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

$ mmark --ext-punctuationSomething---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 theGHC syntaxhighlighterpackage to highlight code blocks with"haskell" info string using lexer ofGHC itself.

The resulting HTML will be rendered as describedhere.

Example:

$ mmark --ext-ghc-highlighterSome Haskell:```haskellmain :: 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 theskylightingpackage to render code blocks with info strings that result in a successfullookup from the syntax table that comes with the library.

The resulting HTML will be rendered as describedhere.

Example:

$ mmark --ext-skylightingSome Haskell:```haskellmain :: 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>

Table of contents

• Option:--ext-toc RANGE

Replace the code block with info string"toc" by table of contentsassembled from headings with levels fromN toM, whereN-M isRANGE.

For example:

$ mmark --ext-toc 2-4# Story of my life```toc```## Charpter 1Foo.## Chapter 2Bar.### SomethingBaz.----------------------- 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 inthe GitHub issue tracker forthis project.

Pull requests are also welcome.

License

Copyright © 2018–present Mark Karpov

Distributed under BSD 3 clause license.

MMark CLI 0.0.5.2

• Maintenance release with more minimal dependencies.

MMark CLI 0.0.5.1

• Dropped support for GHC 8.6 and older.
• Works with aeson 2.

MMark CLI 0.0.5.0

• Added support for theghcSyntaxHighlighter extension. Only availablewhen compiled with GHC >= 8.4.1.

MMark CLI 0.0.4.0

• This version works withmmark-0.0.6.0 andmegaparsec-7.0.0.

MMark CLI 0.0.3.0

• This version works withmmark-ext-0.2.0.0 and later.

MMark CLI 0.0.2.0

• Added two new extensions: footnotes (--ext-footnotes) and MathJaxsupport (--ext-mathjax).

MMark CLI 0.0.1.0

• Initial release.