Module Omd

A markdown parser in OCaml, with no extra dependencies.

This module represents this entire Markdown library written in OCaml only.

Its main purpose is to allow you to use the Markdown library while keeping you away from the other modules.

If you want to extend the Markdown parser, you can do it without accessing any module of this library but this one, and by doing so, you are free from having to maintain a fork of this library.

N.B. This module is supposed to be reentrant, if it's not then please report the bug.

Representation of Markdown documents

type t = element list

Representation of a Markdown document.

and ref_container = < add_ref : string -> string -> string -> unit; get_ref : string -> (string * string) option; get_all : (string * (string * string)) list; >
and element = Omd_representation.element =
| H1 of t

Header of level 1

| H2 of t

Header of level 2

| H3 of t

Header of level 3

| H4 of t

Header of level 4

| H5 of t

Header of level 5

| H6 of t

Header of level 6

| Paragraph of t

A Markdown paragraph (must be enabled in of_string)

| Text of string

Text.

| Emph of t

Emphasis (italic)

| Bold of t

Bold

| Ul of t list

Unumbered list

| Ol of t list

Ordered (i.e. numbered) list

| Ulp of t list
| Olp of t list
| Code of name * string

Code(lang, code) represent code within the text (Markdown: `code`). The language lang cannot be specified from Markdown, it can be from of_string though or when programatically generating Markdown documents. Beware that the code is taken verbatim from Markdown and may contain characters that must be escaped for HTML.

| Code_block of name * string

Code_block(lang, code): a code clock (e.g. indented by 4 spaces in the text). The first parameter lang is the language if specified. Beware that the code is taken verbatim from Markdown and may contain characters that must be escaped for HTML.

| Br

(Forced) line break

| Hr

Horizontal rule

| NL

Newline character. Newline characters that act like delimiters (e.g. for paragraphs) are removed from the AST.

| Url of href * t * title
| Ref of ref_container * name * string * fallback
| Img_ref of ref_container * name * alt * fallback
| Html of name * (string * string option) list * t
| Html_block of name * (string * string option) list * t
| Html_comment of string

An HTML comment, including "<!--" and "-->".

| Raw of string

Raw: something that shall never be converted

| Raw_block of string

Raw_block: a block with contents that shall never be converted

| Blockquote of t

Quoted block

| Img of alt * src * title
| X of < name : string; to_html : ?⁠indent:int -> (t -> string) -> t -> string option; to_sexpr : (t -> string) -> t -> string option; to_t : t -> t option; >

A element of a Markdown document.

and fallback = < to_string : string; to_t : t; >

Fallback for references in case they refer to non-existant references

and name = string

Markdown reference name.

and alt = string

HTML img tag attribute.

and src = string

HTML attribute.

and href = string

HTML attribute.

and title = string

HTML attribute.

type code_stylist = lang:string -> string -> string

Function that takes a language name and some code and returns that code with style.

Input and Output

val of_string : ?⁠extensions:Omd_representation.extensions -> ?⁠default_lang:name -> string -> t

of_string s returns the Markdown representation of the string s.

parameter lang

language for blocks of code where it was not specified. Default: "".

If you want to use a custom lexer or parser, use Omd_lexer.lex and Omd_parser.parse.

val of_bigarray : ?⁠extensions:Omd_representation.extensions -> ?⁠default_lang:name -> Omd_lexer.bigstring -> t

As of_string, but read input from a bigarray rather than from a string.

val set_default_lang : name -> t -> t

set_default_lang lang md return a copy of md where the language of all Code or Code_block with an empty language is set to lang.

val to_html : ?⁠override:(Omd_representation.element -> string option) -> ?⁠pindent:bool -> ?⁠nl2br:bool -> ?⁠cs:code_stylist -> t -> string

Translate markdown representation into raw HTML. If you need a full HTML representation, you mainly have to figure out how to convert Html of string and Html_block of string into your HTML representation.

val to_markdown : t -> string

Translate markdown representation into textual markdown.

val to_text : t -> string

Translate markdown representation into raw text.

Tansforming Markdown documents

val toc : ?⁠start:int list -> ?⁠depth:int -> t -> t

toc md returns toc a table of contents for md.

parameter start

gives the section for which the TOC must be built. For example ~start:[2;3] will build the TOC for subsections of the second H1 header, and within that section, the third h2 header. If a number is 0, it means to look for the first section at that level but stop if one encounters any other subsection. If no subsection exists, an empty TOC [] will be returned. Default: [] i.e. list all sections, starting with the first H1.

parameter depth

the table of contents. Default: 2.