Module Cmarkit_latex

Rendering CommonMark to L^AT_EX.

Generates L^AT_EX 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

Renderer

Render functions

Only useful if you extend the renderer.

L^AT_EX integration notes

Along with the built-in graphicx package, the following L^AT_EX 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 characters

See the sections below for more details.

Character encoding

The output is UTF-8 encoded. It became the the default encoding for L^AT_EX 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 L^AT_EX 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 doc

Ignore this: ".