markdown-ng🔗ℹ

1 Quick start🔗ℹ

1.1 Syntax supported🔗ℹ

John Gruber’s original description.
Enhancements controlled by the current-strict-markdown? parameter.

1.2 Use at the command line, to generate HTML🔗ℹ

You can run this at the command-line: Pipe in markdown and it pipes out HTML.

$ raco md
I am _emph_ and I am **strong**.
^D
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" /></head>
<body>
I am emph and I am strong.</body></html>

1.3 Use as a library, to generate xexprs and HTML🔗ℹ

Use parse-markdown to convert a string? or path? to a (listof xexpr?).

You can modify the (listof xexpr?), splice it into the body element of an (html ...) wrapper, and convert to HTML text.

Examples:

(require markdown-ng)

; 1. Parse string to a list of xexprs

(define xs (parse-markdown "I am _emph_ and I am **strong**."))

xs
'((p () "I am " (em () "emph") " and I am " (strong () "strong") "."))

; 2. Optionally, process the xexprs somehow:
; ... nom nom nom ...
; 3. Splice them into an HTML `xexpr` and...
; 4. Convert to HTML text:

(display-xexpr `(html ()
 (head ())
 (body () ,@xs)))
<html>
<head></head>
<body>
 I am emph and I am strong.</body></html>

display-xexpr is provided as a "warm bowl of porridge" — in between xexpr->string (which does no formatting and isn’t very diff-friendly) and display-xml (which does too much and can for example break <pre> formatting).

1.4 Use as a library, to generate "pre-Scribble"🔗ℹ

The xexprs returned by read-markdown can also be fed to the function xexprs->scribble-pres, which returns a Scribble representation — a list of pre-part?, pre-flow? or pre-content? items — acceptable to Scribble’s decode, which returns a Scribble part. The part can in turn be fed to any of the Scribble renderers: HTML, LaTeX, plain text, or even Markdown (if you’d like to go around in circles).

#lang racket/base

(require markdown-ng
         markdown-ng/scrib
         net/sendurl
         racket/class
         racket/format
         racket/runtime-path
         scribble/base-render
         scribble/decode
         scribble/html-render)

(define work-dir (find-system-path 'temp-dir))

(define (build-html-doc docs dest-file)
  (let* ([renderer (new (render-mixin render%) [dest-dir work-dir])]
         [fns      (list (build-path work-dir dest-file))]
         [fp       (send renderer traverse docs fns)]
         [info     (send renderer collect  docs fns fp)]
         [r-info   (send renderer resolve  docs fns info)])
    (send renderer render docs fns r-info)
    (send renderer get-undefined r-info)))

(define-runtime-path test.md "test/test.md")

(define part (decode
              (xexprs->scribble-pres
               (with-input-from-file test.md read-markdown))))

(build-html-doc (list part) "test.html")

(send-url (~a "file://" work-dir "test.html"))

2 Notes🔗ℹ

Originally this was implemented using a pile of regular expressions, somewhat like how Markdown.pl works — but complicated by creating xexprs not an HTML string. On the bright side, I wrote nearly a hundred unit tests.

In October 2013 I redesigned it to be a "real" parser with a grammar, using Stephen Chang’s parsack, a monadic parser combinator library. The grammar was developed by looking first at peg-markdown and later at pandoc. For a few edge cases I found Babelmark and Babelmark2 helpful to compare result with many other implementations. The many unit tests from the old version also helped.

2.1 Links🔗ℹ

3 API🔗ℹ

(require markdown-ng)

package: markdown-ng

The markdown-ng module provides all bindings from the markdown-ng/display-xexpr, markdown-ng/parse, and markdown-ng/toc modules.

3.1 Parsing Markdown🔗ℹ

(require markdown-ng/parse)

package: markdown-ng

procedure
(parse-markdown input
[ footnote-prefix-symbol?]) → (listof xexpr?)
input : (or/c path? string?)
footnote-prefix-symbol? : symbol? = (gensym)

Parses an entire markdown file.

When given a string?, parses the string as a markdown file. When given a path?, calls file->string and parses the result.

Deletes all \r (including but not limited to \r\n).
Appends a \r\n to simplify whole-document processing.

parameter
(current-strict-markdown?) → boolean?
(current-strict-markdown? strict?) → void?
strict? : boolean?
= #f

Setting this parameter true will use a strict markdown parser. In other words, it will disable the following enhancements to the original markdown syntax:

Fenced code blocks using triple backticks ```. An optional language descriptor may follow the opening backticks. This results in the code element getting a class attribute whose value is brush: lang.
Inline code using single backticks may be followed by a language descriptor in square brackets. This results in the code element getting a class attribute whose value is brush: lang.
Heading elements get an id attribute whose value is a "slug" of the heading text.
Images alone in their own paragraph are nested in a in div.figure along with a p.caption element following the img.
"Smart" punctuation (hyphens, dashes, single and double quotes, aspostrophes, prime, ellipses).
Footnote definitions and references as in PHP Markdown Extra and Python-Markdown.
Support for math-jax expressions — inline within \$ and \$ delimiters and display within \\[ and \\] delimiters — resulting in script elements with type=math/tex.

procedure
(read-markdown [footnote-prefix-symbol?]) → (listof xexpr?)
footnote-prefix-symbol? : symbol? = (gensym)

Parses markdown input from current-input-port.

NOTE: This function is deprecated; use parse-markdown, instead.

3.2 Building a Table of Contents🔗ℹ

(require markdown-ng/toc)

package: markdown-ng

procedure
(toc xexprs) → xexpr?
xexprs : (listof xexpr?)

Builds a table of contents from the given markdown expression.

Example:

> (toc (parse-markdown (string-join '("# 1" "## 1.1" "# 2" "## 2.1") "\n\n")))
'(div
  ((class "toc"))
  (ol
   (li (a ((href "#1")) "1") (ul (li (a ((href "#11")) "1.1"))))
   (li (a ((href "#2")) "2") (ul (li (a ((href "#21")) "2.1"))))))

3.3 Displaying Parsed Markdown🔗ℹ

(require markdown-ng/display-xexpr)

package: markdown-ng

procedure
(display-xexpr xexpr) → any/c
xexpr : xexpr?

Prints an HTML representation of xexpr to current-output-port.

procedure
(xexpr->string xexpr) → string?
xexpr : xexpr?

Unlike Racket’s xexpr->string, this does not over-aggressively encode chars like & in attribute values.

3.4 Generating Pre-Scribble🔗ℹ

(require markdown-ng/scrib)

package: markdown-ng

The bindings documented in this section are not provided by the markdown-ng module.

procedure
(xexprs->scribble-pres xexprs)
→ (listof (or/c pre-part? pre-flow? pre-content?))
xexprs : (listof xexpr?)

Given a list of xexprs representing valid HTML, return a Scribble representation: A list of pre-part?, pre-flow?, or pre-content? acceptable to Scribble’s decode.

Although this could be generalized, currently it’s only intended to handle the subset of HTML that read-markdown returns.