Module Cmarkit_commonmark

CommonMark to CommonMark renderer.

The renderer can be customized to handle abstract syntax tree extensions or override parts of the default rendering. this example.

Rendering

type funs

The type for rendering functions.

val of_doc : ?funs:funs -> layout:bool -> Cmarkit.t -> string

of_doc ~funs ~layout d generates an CommonMark document for d.

  • layout. If true indicates the the layout information stored in node metadata should be used. Use this if you want a best-effort user input layout preservation.
  • funs are the rendering functions to use (defaults to default). If funs functions ever return false, unknown is used as a last resort.
val buffer_add_doc : Stdlib.Buffer.t -> ?funs:funs -> layout:bool -> Cmarkit.t -> unit

buffer_add_doc b ~funs ~layout d is like of_doc but adds the rendering to b.

Renderer

type t

The type for CommonMark CommonMark renderers.

val layout : t -> bool

safe r is true iff a node layout information should be used for output.

val block : t -> Cmarkit.block -> unit

block r b renders block b on r.

val inline : t -> Cmarkit.inline -> unit

inline r i renders inline i on r.

val str : t -> string -> unit

str r s renders string s on r. HTML markup delimiters are properly escaped.

val unescaped_char : t -> char -> unit

unescaped_char r c renders the raw character c on r.

val unescaped_uchar : t -> Stdlib.Uchar.t -> unit

unescaped_uchar r u renders the raw character u on r.

val unescaped_str : t -> string -> unit

unescaped_str r s renders the raw string s on r.

Rendering functions

val funs : ?block:(t -> Cmarkit.block -> bool) -> ?inline:(t -> Cmarkit.inline -> bool) -> unit -> funs

funs ~block ~inline () are rendering functions. The block and inline functions:

  • Must return true on values they rendered.
  • Must return false on values they did not render.
  • Must use block and inline with the renderer they receive if they need to invoke the renderer recursively.
  • Should be considerate of layout renderings.
  • Default to fun _ _ -> false.
val default : funs

default are the default CommonMark rendering functions.

On safe renderings:

  • Raw HTML is discarded and replaced by an HTML comment in the output.
  • URL that satify Cmarkit.is_unsafe_link are replaced by the empty string
val unknown : funs

unknown are the last resort rendering functions. Its functions always render an HTML comment indicating an unknown block or inline value was found and return true.

val compose : funs -> funs -> funs

compose g f renders first with f and if the rendering function returned false falls backs on g.

Custom renderer example

Let's assume you want to:

  1. Extend the abstract syntax tree with a `Doc block which allows to splice documents in another one.
  2. Slightly alter default's rendering of thematic breaks.
  3. Otherwise use the default renderer.

This boils down to add a new case to the syntax tree, define a new funs value whose block rendering function handles the extension and thematic breaks and invoke them before the default rendering functions by using compose.

type Cmarkit.block += Doc of Cmarkit.t

let custom =
  let block r = function
  | Doc (blocks, _) ->
      (* Note, it's important to recurse via Cmarkit_html.block *)
      List.iter (Cmarkit_html.block r) blocks; true
  | Cmarkit.Thematic_break _ ->
      Cmarkit_html.unsafe_str r "<hr class='my_tweak' />"; true
  | _ -> false
  in
  let funs = Cmarkit_html.funs ~block () in
  Cmarkit_html.compose Cmarkit_html.std funs

The rendering functions custom can now be used with the funs argument of the of_doc function.