https://github.com/mmark-md/mmark-cli
Command line interface to the MMark markdown processor
https://github.com/mmark-md/mmark-cli
cli haskell mmark
Last synced: 9 months ago
JSON representation
Command line interface to the MMark markdown processor
- Host: GitHub
- URL: https://github.com/mmark-md/mmark-cli
- Owner: mmark-md
- License: other
- Created: 2018-01-10T15:18:19.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2025-04-23T18:36:57.000Z (9 months ago)
- Last Synced: 2025-04-23T19:44:55.380Z (9 months ago)
- Topics: cli, haskell, mmark
- Language: Haskell
- Homepage:
- Size: 93.8 KB
- Stars: 12
- Watchers: 2
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# MMark CLI
[](http://opensource.org/licenses/BSD-3-Clause)
[](https://hackage.haskell.org/package/mmark-cli)
[](http://stackage.org/nightly/package/mmark-cli)
[](http://stackage.org/lts/package/mmark-cli)
[](https://github.com/mmark-md/mmark-cli/actions/workflows/ci.yaml)
* [Templates](#templates)
* [Extensions](#extensions)
* [Comment paragraph](#comment-paragraph)
* [Font Awesome](#font-awesome)
* [Footnotes](#footnotes)
* [Kbd tags](#kbd-tags)
* [Link targets](#link-targets)
* [MathJax](#mathjax)
* [Email obfuscation](#email-obfuscation)
* [Punctuation prettifier](#punctuation-prettifier)
* [GHC syntax highlighter](#ghc-syntax-highlighter)
* [Skylighting](#skylighting)
* [Table of contents](#table-of-contents)
* [Contribution](#contribution)
* [License](#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](https://mustache.github.io/mustache.5.html), as implemented by
the [stache](https://hackage.haskell.org/package/stache) library. The
library conforms to the version 1.1.3 of the official [Mustache
specification](https://github.com/mustache/spec), 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`](https://hackage.haskell.org/package/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
First.
Third.
```
### 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: .
A more interesting example: .
----------------------- Control-D
Here is the user icon: .
A more interesting example:
.
```
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
Here goes some text 1.
-
Here we have the footnote.
↩
```
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
To enable that mode press Ctrl+A.
```
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
This link
opens in new tab.
```
### 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
Let's talk about
\(A\) and
\(B\).
\[A \xrightarrow{f} B\]
````
### 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 , if you can!
----------------------- Control-D
Send all your spam to
Enable JavaScript to see this email, if you can!
```
You'll also need to include jQuery and this bit of JS code for the magic to
work:
```java-script
$(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
Something—we don’t know what, happened…
```
### GHC syntax highlighter
* Option: `--ext-ghc-highlighter`
Use the [GHC syntax
highlighter](https://hackage.haskell.org/package/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](https://hackage.haskell.org/package/mmark-ext/docs/Text-MMark-Extension-GhcSyntaxHighlighter.html#v:ghcSyntaxHighlighter).
Example:
````
$ mmark --ext-ghc-highlighter
Some Haskell:
```haskell
main :: IO ()
main = return ()
```
----------------------- Control-D
Some Haskell:
main :: IO ()
main = return ()
````
### Skylighting
* Option: `--ext-skylighting`
Use the [skylighting](https://hackage.haskell.org/package/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](https://hackage.haskell.org/package/mmark-ext/docs/Text-MMark-Extension-Skylighting.html#v:skylighting).
Example:
````
$ mmark --ext-skylighting
Some Haskell:
```haskell
main :: IO ()
main = return ()
```
----------------------- Control-D
Some Haskell:
main :: IO ()
main = return ()
````
### Table of contents
* 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
Story of my life
Charpter 1
Foo.
Chapter 2
Bar.
Something
Baz.
````
## Contribution
Issues, bugs, and questions may be reported in [the GitHub issue tracker for
this project](https://github.com/mmark-md/mmark-cli/issues).
Pull requests are also welcome.
## License
Copyright © 2018–present Mark Karpov
Distributed under BSD 3 clause license.