Wondering what’s next for npm?Check out our public roadmap! »

    markdown-clj

    1.10.3 • Public • Published

    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.

    Install

    npm i markdown-clj

    DownloadsWeekly Downloads

    1

    Version

    1.10.3

    License

    EPL-1.0

    Unpacked Size

    53.2 kB

    Total Files

    8

    Last publish

    Collaborators

    • avatar