Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here

markdown-clj

Markdown parser in Clojure

Subscribe to updates I use markdown-clj


Statistics on markdown-clj

Number of watchers on Github 354
Number of open issues 13
Average time to close an issue 26 days
Main language Clojure
Average time to merge a PR about 12 hours
Open pull requests 2+
Closed pull requests 9+
Last commit over 1 year ago
Repo Created almost 8 years ago
Repo Last Updated over 1 year ago
Size 1.31 MB
Organization / Authoryogthos
Latest Release0.9.62
Contributors20
Page Updated
Do you use markdown-clj? Leave a review!
View open issues (13)
View markdown-clj activity
View on github
Fresh, new opensource launches πŸš€πŸš€πŸš€
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating markdown-clj for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

Markdown parser written in Clojure/Script

CircleCI Downloads

Demo

You can try out the parser here.

Installation

A markdown parser that compiles to both Clojure and ClojureScript.

Clojars Project

Note: markdown-clj versions prior to 0.9.68 requires Clojure 1.2+ to run, versions 0.9.68+ require Clojure 1.7.

Usage Clojure

Markdown-clj can be invoked either by calling md-to-html or md-to-html-string functions.

The md-to-html function accepts an input containing Markdown markup and an output where the resulting HTML will be written. The input and output parameters will be passed to a reader and a writer respectively:

(ns foo
  (:use markdown.core))

(md-to-html "input.md" "output.html")

(md-to-html (input-stream "input.md") (output-stream "test.txt"))

The md-to-html-string function accepts a string with markdown content and returns a string with the resulting HTML:

(md-to-html-string "# This is a test\nsome code follows\n```clojure\n(defn foo [])\n```")
<h1> This is a test</h1>some code follows<pre><code class="clojure">&#40;defn foo &#91;&#93;&#41;
</code></pre>

Both md-to-html and md-to-html-string accept optional parameters:

Specifying :heading-anchors will create anchors for the heading tags, eg:

(markdown/md-to-html-string "###foo bar BAz" :heading-anchors true)

<h3 id=\"foo&#95;bar&#95;baz\">foo bar BAz</h3>

The code blocks default to a highlight.js compatible format of:

<pre><code class="clojure">some code</code></pre>

Specifying :code-style will override the default code class formatting for code blocks, eg:

(md-to-html-string "# This is a test\nsome code follows\n```clojure\n(defn foo [])\n```"
                   :code-style #(str "class=\"brush: " % "\""))
<h1> This is a test</h1>some code follows<pre><code class="brush: clojure">
&#40;defn foo &#91;&#93;&#41;
</code></pre>

reference style links

The parser defaults to using inline reference for performance reasons, to enable reference style links pass in the :reference-links? true option:

(md-to-html-string
  "This is [an example][id] reference-style link.

   [id]: http://example.com/ 'Optional Title Here'"
   :reference-links? true)

footnotes

To enable footnotes, pass the :footnotes? true option:

(md-to-html-string
  "Footnotes will appear automatically numbered with a link to the footnote at bottom of the page [^footnote1].

  [^footnote1]: The footnote will contain a back link to to the referring text."
  :footnotes? true)

Metadata

The metadata encoded using the syntax described by MultiMarkdown can be optionally extracted from the document.

The md-to-html function will attempt to parse the metadata when passed the :parse-meta? true option and return it as its output. Additionally, md-to-html-string-with-meta function can be used to parse string input. The function returns a map with two keys, :html containing the parsed HTML, and :metadata containing a map with the metadata included at the top of the document.

The value of each key in the metadata map will be a list of either 0, 1 or many strings. If a metadata value ends in two spaces then the string will end in a newline. If a line does not contain a header and has at least 4 spaces in front of it then it will be considered to be a member of the last key that was found.

(let [input    (new StringReader text)
      output   (new StringWriter)
      metadata (md-to-html input output :parse-meta? true)
      html     (.toString output)]
  {:metadata metadata :html html})

(md-to-html-string-with-meta
  "Author: Rexella van Imp
    Kim Jong-un
Date: October 31, 2015

   # Hello!")

{:metadata {:author ["Rexella van Imp"
                     "Kim Jong-un"],
            :date ["October 31, 2015"]},
 :html "<h1>Hello!</h1>"}

Selectively inhibiting the Parser

If you pass :inhibit-separator "some-string", then any text within occurrences of some-string will be output verbatim, eg:

(md-to-html-string "For all %$a_0, a_1, ..., a_n in R$% there is _at least one_ %$b_n in R$% such that..."
                   :inhibit-separator "%")
For all $a_0, a_1, ..., a_n in R$ there is <i>at least one</i> $b_n in R$ such that...

This may be useful to use markdown-clj along with other parsers of languages with conflicting syntax (e.g. asciimath2jax).

If you need to output the separator itself, enter it twice without any text inside. Eg:

(md-to-html-string "This is one of those 20%% vs 80%% cases."
                   :inhibit-separator "%")
This is one of those 20% vs 80% cases.

Some caveats:

  • Like other tags, this only works within a single line.

  • If you remove the default transformers with :replacement-transformers (which see below), inhibiting will stop working.

  • Currently, dashes (-- and ---) can't be suppressed this way.

Customizing the Parser

Additional transformers can be specified using the :custom-transformers key. A transformer function must accept two arguments. First argument is the string representing the current line and the second is the map representing the current state.

The default state keys are:

  • :code - inside a code section
  • :codeblock - inside a code block
  • :eof - end of file
  • :heading - in a heading
  • :hr - in a horizontal line
  • :lists - inside a list
  • :blockquote - inside a blockquote
  • :paragraph - in a paragraph
  • :last-line-empty? - was last line an empty line?

For example, if we wanted to add a transformer that would capitalize all text we could do the following:

(defn capitalize [text state]
  [(.toUpperCase text) state])

(markdown/md-to-html-string "#foo" :custom-transformers [capitalize])
<H1>FOO</H1>

Alternatively, you could provide a custom set of transformers to replace the default transformers using the :replacement-transformers key.

(markdown/md-to-html-string "#foo" :replacement-transformers [capitalize])

This can also be used to add preprocessor transformers. For example, if we wanted to sanitize any image links we could do the following:

(use 'markdown.transformers 'markdown.core)

(defn escape-images [text state]
  [(clojure.string/replace text #"(!\[.*?\]\()(.+?)(\))" "") state])

(markdown/md-to-html-string
  "foo ![Alt text](/path/to/img.jpg \"Optional Title\") bar [text](http://test)"
  :replacement-transformers (cons escape-images transformer-vector))
"<p>foo  bar <a href='http://test'>text</a></p>"

Usage ClojureScript

The ClojureScript portion works the same as above except that the entry function is called md->html. It accepts a string followed by the options as its input, and returns the resulting HTML string:

(ns myscript
  (:require [markdown.core :refer [md->html]]))

(.log js/console
  (md->html "##This is a heading\nwith a paragraph following it"))

(.log js/console
  (md->html "# This is a test\nsome code follows\n```clojure\n(defn foo [])\n```"
               :code-style #(str "class=\"" % "\"")))

(md->html-with-meta "# This is a test\nsome code follows\n```clojure\n(defn foo [])\n```")

Usage JavaScript

console.log(markdown.core.mdToHtml("##This is a heading\nwith a paragraph following it"));

Supported syntax

Control characters can be escaped using \

\\ backslash
\` backtick
\* asterisk
\_ underscore
\{ curly braces
\}
\[ square brackets
\]
\( parentheses
\)
\# hash mark
\+ plus sign
\- minus sign (hyphen)
\. dot
\! exclamation mark

Basic Elements

Blockquote, Strong, Bold, Bold-Italic, Emphasis, Italics, Heading, Line, Linebreak, Paragraph, Strikethrough

Links

Image, Link

Automatic Links

This is a shortcut style for creating β€œautomatic” links for URLs and email addresses:

<http://example.com/>

will be turned this into:

<a href="http://example.com/">http://example.com/</a>

Automatic links for email addresses work similarly, except that they are hex encoded:

<address@example.com&>

will be turned into:

<a href=\"&#x61&#x64&#x64&#x72&#x65&#x73&#x73&#x40&#x65&#x78&#x61&#x6d&#x70&#x6c&#x65&#x2e&#x63&#x6f&#x6d\">&#x61&#x64&#x64&#x72&#x65&#x73&#x73&#x40&#x65&#x78&#x61&#x6d&#x70&#x6c&#x65&#x2e&#x63&#x6f&#x6d</a>

Lists

Ordered List, Unordered List

Code

Code Block, Indented Code, Inline Code


Heading

the number of hashes indicates the level of the heading

# Heading

##Sub-heading

### Sub-sub-heading

headings can also be defined using = and - for h1 and h2 respectively

Heading 1
=========

Heading 2
---------

Line

***

* * *

*****

- - -

______

Linebreak

If a line ends with two or more spaces a <br /> tag will be inserted at the end.

Emphasis

*foo*

Italics

_foo_

Strong

**foo**

Bold

__foo__

Bold-Italic

***bold italic***

Blockquote

> prefixes regular blockquote paragraphs. >- prefixes a blockquote footer that can be used for author attribution.

>This is a blockquote
with some content

>this is another blockquote

> Everyone thinks of changing the world,
but no one thinks of changing himself.
>- Leo Tolstoy

Paragraph

This is a paragraph, it's
split into separate lines.

This is another paragraph.

Unordered List

indenting an item makes it into a sublist of the item above it, ordered and unordered lists can be nested within one another. List items can be split over multiple lines.

* Foo
* Bar
 * Baz
* foo
* bar

   * baz
     1. foo
     2. bar
        more content
        ## subheading
        ***
        **strong text** in the list

   * fuzz

      * blah
      * blue
* brass

Ordered List

1. Foo
2. Bar
3. Baz

Inline Code

Any special characters in code will be escaped with their corresponding HTML codes.

Here's some code `x + y = z` that's inlined.

Code block

Using three backquotes indicates a start of a code block, the next three backquotes ends the code block section. Optionally, the language name can be put after the backquotes to produce a tag compatible with highlight.js, eg:

```clojure

(defn foo [bar] baz)

```

Indented Code

indenting by at least 4 spaces creates a code block

some
code
here

note: XML is escaped in code sections

Strikethrough

~~foo~~

Superscript

a^2 + b^2 = c^2

Link

[github](http://github.com)
Reference Link
This is [an example][id] reference-style link.

[id]: http://example.com/  "Optional Title Here"

note: reference links require the :reference-links? option to be set to true

Footnote

"Footnotes will appear automatically numbered with a link to the footnote at bottom of the page [^footnote1].
[^footnote1]: The footnote will contain a back link to to the referring text."

note: to enable footnotes, the :footnotes? option must be set to true.

Image

![Alt text](http://server/path/to/img.jpg)
![Alt text](/path/to/img.jpg "Optional Title")
Image Reference
This is ![an example][id] reference-style image descriptor.

[id]: http://example.com/  "Optional Title Here"

note: reference links require the :reference-links? option to be set to true

Image Link

[![Continuous Integration status](https://secure.travis-ci.org/yogthos/markdown-clj.png)](http://travis-ci.org/yogthos/markdown-clj)

Table

You can create tables by assembling a list of words and dividing them with hyphens - (for the first row), and then separating each column with a pipe |:

| First Header  | Second Header |
| ------------- | ------------- |
| Content Cell  | Content Cell  |
| Content Cell  | Content Cell  |

By including colons : within the header row, you can define text to be left-aligned, right-aligned, or center-aligned:

| Left-Aligned  | Center Aligned  | Right Aligned |
| :------------ |:---------------:| -----:|
| col 3 is      | some wordy text | $1600 |
| col 2 is      | centered        |   $12 |
| zebra stripes | are neat        |    $1 |

A colon on the left-most side indicates a left-aligned column; a colon on the right-most side indicates a right-aligned column; a colon on both sides indicates a center-aligned column.

Limitations

The parser reads the content line by line, this means that tag content is not allowed to span multiple lines.

License

Copyright 2015 Dmitri Sotnikov

Distributed under the Eclipse Public License, the same as Clojure.

markdown-clj open issues Ask a question     (View All Issues)
  • about 3 years Footnotes cannot span multiple lines
  • about 3 years List with multiple paragraphs
  • over 3 years When a linebreak occurs in a link, the link is not parsed.
  • over 3 years inline language code highlight
  • almost 4 years Reference image urls not supported
  • almost 4 years GFM support and checkboxes
  • almost 4 years named link support when link text matches name
  • almost 4 years Wrapping transformed output in additional HTML tags
  • about 4 years Easy way to get plain text from markdown text?
markdown-clj open pull requests (View All Pulls)
  • Test to exhibit bug in link HTML encoding.
  • Fixes bug when freezing text inside a multi-line entity
markdown-clj list of languages used
Other projects in Clojure