Legend:
Library
Module
Module type
Parameter
Class
Class type
Library
Module
Module type
Parameter
Class
Class type
package cmarkit
Rendering CommonMark to LATEX.
Generates LATEX fragments, consult the integration notes for requirements on the document.
See a quick example and another one.
Warning. Rendering outputs are unstable, they may be tweaked even between minor versions of the library.
Rendering
val of_doc : ?backend_blocks:bool -> Cmarkit.Doc.t -> stringof_doc d is a LATEX fragment for d. See renderer for more details and documentation about rendering options.
Renderer
val renderer : ?backend_blocks:bool -> unit -> Cmarkit_renderer.trenderer is a default LATEX renderer. This renders the strict CommonMark abstract syntax tree and the supported Cmarkit extensions.
The inline, block and document renderers always return true. Unknown block and inline values are rendered by a LATEX comment.
The following options are available:
backend_blocks, iftrue, code blocks with language=latexare written verbatim in the output and any other code block whose langage starts with=is dropped. Defaults tofalse.
See this example to extend or selectively override the renderer.
Render functions
Only useful if you extend the renderer.
val newline : Cmarkit_renderer.context -> unitnewline c starts a new line. Except on the first call on c which is a nop.
val latex_escaped_uchar : Cmarkit_renderer.context -> Uchar.t -> unitlatex_escaped_uchar c u renders the UTF-8 encoding of u on c propertly escaped for LATEX. That is the characters & % $ # _ { } ~ ^ \ are escaped. This also renders U+0000 to Uchar.rep.
buffer_add_latex_escaped_uchar is latex_escaped_uchar but appends to a buffer value.
val latex_escaped_string : Cmarkit_renderer.context -> string -> unitlatex_escaped_string c s renders string s on c with characters & % $ # _ { } ~ ^ \ escaped. This also escapes U+0000 to Uchar.rep.
val buffer_add_latex_escaped_string : Buffer.t -> string -> unitbuffer_add_latex_escaped_string is latex_escaped_string but acts on a buffer value.
LATEX integration notes
Along with the built-in graphicx package, the following LATEX packages are needed to use the outputs of the default renderer:
tlmgr install enumitem listings hyperref # Required tlmgr install ulem # Strikethrough extension tlmgr install bera fontspec # Optional
This means you should have at least the following in your document preamble:
% Required
\usepackage{graphicx}
\usepackage{enumitem}
\usepackage{listings}
\usepackage{hyperref}
\usepackage[normalem]{ulem} % Strikethrough extension
% Optional
\usepackage[scaled=0.8]{beramono} % A font for code blocks
\usepackage{fontspec} % Supports more Unicode charactersSee the sections below for more details.
Character encoding
The output is UTF-8 encoded. It became the the default encoding for LATEX in 2018. But if you are using an older version a \usepackage[utf8]{inputenc} may be needed.
Using xelatex rather than pdflatex will not get stuck on missing glyphs.
Autolinks and links
The hyperref package is used to render links (\href) and autolink (\url). Link destination starting with a # are assumed to refer to section labels and are rendered using the \hyperref macro, with the # chopped.
Images
Images are inserted using the graphicx's package. Only images with relative URLs are supported, those that point to external ressources on the www are turned into links.
Section labels
Section labels are added to the output whenever Cmarkit.Block.Heading.id holds a value. If the identifier already exists it is made unique by appending "-" and the first number starting from 1 that makes it unique. Also the character _ seems problematic in labels even when escaped, we map it to - (if you know any better get in touch).
Lists
To support the starting point of ordereded lists without having to fiddle with enumi counters, the enumitem package is used.
Code blocks
If a language lang can be extracted from a code block info string, the listings package is used with the corresponding language in a lstlisting environment. Otherwise the built-in verbatim environment is used.
Note that the listings package has no definition for the ocaml language, the default renderings are a bit subpar and break on character literals with double quotes. This improves things:
\lstset{
columns=[c]fixed,
basicstyle=\small\ttfamily,
keywordstyle=\bfseries,
upquote=true,
commentstyle=\slshape,
breaklines=true,
showstringspaces=false}
\lstdefinelanguage{ocaml}{language=[objective]caml,
% Fixes double quotes in char literals
literate={'"'}{\textquotesingle "\textquotesingle}3
{'\\"'}{\textquotesingle \textbackslash"\textquotesingle}4,
}Document frame
The default renderer only generates LATEX fragments. You may want to add a document frame. For example:
let latex_doc_of_md ?(title = "") md =
let doc = Cmarkit.Doc.of_string md in
let r = Cmarkit_latex.renderer () in
let buffer_add_doc = Cmarkit_renderer.buffer_add_doc r in
let buffer_add_title = Cmarkit_latex.buffer_add_latex_escaped_string in
let maketitle = if title = "" then "" else {|\maketitle|} in
Printf.kbprintf Buffer.contents (Buffer.create 1024)
{|\documentclass{article}
\usepackage{graphicx}
\usepackage{enumitem}
\usepackage{listings}
\usepackage{hyperref}
\usepackage[normalem]{ulem}
\usepackage[scaled=0.8]{beramono}
\usepackage{fontspec}
\lstset{
columns=[c]fixed,
basicstyle=\small\ttfamily,
keywordstyle=\bfseries,
upquote=true,
commentstyle=\slshape,
breaklines=true,
showstringspaces=false}
\lstdefinelanguage{ocaml}{language=[objective]caml,
literate={'"'}{\textquotesingle "\textquotesingle}3
{'\\"'}{\textquotesingle \textbackslash"\textquotesingle}4,
}
\title{%a}
\begin{document}
%s
%a
\end{document}|} buffer_add_title title maketitle buffer_add_doc docIgnore this: ".